Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / a68k104.arc / A68K104.MAN next >

Wrap

Text File | 1987-03-18 | 196.4 KB | 6,269 lines

_______________________________________________________________ Advance Operating System User Manual Last Revised April, 1987 _______________________________________________________________ The Advance Operating System is distributed as a USEware product. Creative Software Technology assumes no responsibility for any errors that may appear in this manual. Creative Software Technology, reserves the right to make changes in specifications and other information contained in this user manual without prior notice, and the reader should in all cases consult Creative Software Technology to determine whether any such changes have been made. The Advance Operating System is the property of Creative Software Technology. Use, duplication or disclosure is subject to restrictions stated in Creative Software Technology's Binary Software License Agreement. ADVANCE OPERATING SYSTEM Copyright (C) 1986, 1987 by: Creative Software Technology All Rights Reserved TABLE OF CONTENTS Chapter 1. Introduction to the Advance Operating System.....1-1 1.1 General Features...................................1-4 1.2 AOS/68K Entry Vectors..............................1-8 1.3 Interrupts.........................................1-9 1.4 Configuration Table...............................1-10 1.5 Static Task Control Block.........................1-17 1.6 Task Priorities...................................1-19 1.7 Task States.......................................1-20 1.8 The Balanced System Design........................1-21 Chapter 2. AOS System Calls (Part One)...................2-1 2.1.0 Tsk_switch....................................2-4 2.1.1 Tsk_on........................................2-5 2.1.2 Tsk_off.......................................2-6 2.1.3 Tsk_stat......................................2-7 2.1.4 Tsk_id........................................2-8 2.2.1 Post_box......................................2-9 2.2.2 Send.........................................2-12 2.2.3 Receive......................................2-14 2.2.4 Sendx........................................2-16 2.3.1 Time_set.....................................2-18 2.3.2 Time_read....................................2-19 2.3.3 Tick.........................................2-20 2.3.4 Delay........................................2-21 2.4.1 Put_char.....................................2-22 2.4.2 Get_char.....................................2-23 2.4.3 Key_stat.....................................2-24 2.4.4 Trn_stat.....................................2-26 2.5.1 Gt_cpt.......................................2-27 2.5.2 G_stk........................................2-27 2.5.3 Res_tsk......................................2-28 Chapter 3. AOS System Calls (Part Two)...................3-1 3.1.1 Fetch_mem.....................................3-1 3.1.2 Release_mem...................................3-2 3.1.3 Free_mem......................................3-3 3.2.1 Edc_system....................................3-4 3.2.2 Edc_task......................................3-5 Chapter 4. Error Recovery Interface Software.............4-1 4.1 Error Analysis................................4-2 4.2 Error Correction Word.........................4-3 Chapter 5. Interactive Diagnostic Module.................5-1 APPENDIX Execution Times...............................A-1 Advance Operating System Chapter 1 1.0 INTRODUCTION Congratulations on choosing the ADVANCE OPERATING SYSTEM! This version of ADVANCE is one of the fastest, position and device independent, multitasking operating systems available for the 68000. In many instalations this version of ADVANCE for the 68000 will be THE fastest. Many system designers choose slower operating systems because they claim to run "real-time" and they have been around for awhile. If speed, reliability, and efficiency are your main concerns in the design of your embedded 68000 processor application, then you have made an excellent choice in choosing ADVANCE. We have sacrificed very little versatility in order to create ADVANCE. You will find the functions you need and use the most in multitasking operating systems such as task management, the ability to set up time-slicing, and intertask communication, etc. Every system call has been engineered for the 68000, making full use of it's powerful architecture. ADVANCE system calls are easy to set up and use in a wide variety of applications. Our basic calls can be combined with application algorithms in such a way as to lessen the need for the expensive scheme of dynamic task prioritization and special time-slicing.* The ADVANCE OPERATING SYSTEM is offered in three parts, each sold separately. Part One is the base-section. Intertask syn- chronization, management, communication and all the necessary software to support a fast multitasking kernel is in Part One. Part Two contains the structured AOS Error Recovery Interface software. If your application will be detecting run-time errors, the AOS ERI package can significantly increase system efficiency. Part Three is the AOS Interactive Diagnostic Module. This spe- cial software will decrease the amount of time it takes program- mers to debug their code. The three parts are organized in the following manner: Part Chapter 1 2 2 4 3 5 Copyright (C) 1986, 1987 by Creative Software Technology 1-1 Advance Operating System Chapter 1 The ADVANCE Operating System was created to control a variety of sophisticated production equipment. A machine super- vised by ADVANCE is up to 50% more efficient than an identical machine with a standard operating system. ADVANCE significantly increases product throughput. Many hours of run-time in manu- facturing plants are constantly proving the superior performance of ADVANCE-operated equipment. The optional Error Recovery (ERI) interface software in the ADVANCE Operating System is very powerful. ADVANCE-operated equipment equipped with ERI can easily and quickly recover from many former "machine-down" error conditions with it's unique, structured error recovery data tables. Many other errors can safely be masked and scheduled into a more timely preventative maintenance schedule. This Error Recovery Software permits higher throughput, which is just one of many AOS Balanced System Design benefits. ADVANCE supports structured modular programming. Compli- cated processes may be broken down into small parts (modules). These smaller sections are easier to understand and maintain for the entire useful life of your process applications. The modular design concept behind ADVANCE allows the applications engineer to solve complex, parallel control processes that could be solved no other way. ADVANCE, equipped with the optional Interactive Diagnostic Module (IDM), makes debugging of hardware and software much easier, and works very well with logic analyzers. ADVANCE, for most applications, makes logic analyzers unnecessary because it can easily simulate hardware events on the diagnostic terminal. This simulation makes real hardware bugs easy to locate during integration testing. Also, diagnostic programs can run simul- taneously with user programs, giving the programmer an "inside view" of his software as it runs (a powerful debugging tool!). Unlike typical diagnostics, ADVANCE's IDM allows for breakpoints that stop only the module that hits a breakpoint, while the other modules continue to run. This version of the ADVANCE OPERATING SYSTEM is designed to run on a 68000-based microcomputer. ADVANCE/68000 is very much like a hardware component. It never needs to be modified for special 68000 designs. This means that the system architect can easily build an endless number of software designs around AOS without ever changing it. Copyright (C) 1986, 1987 by Creative Software Technology 1-2 Advance Operating System Chapter 1 The ADVANCE OPERATING SYSTEM is position independent and occupies a 4K ROM space in the target microcomputer's memory, just in front of a user-supplied configuration table. Please refer to section 1-3 for information on how to set up the config- uration table. The user configuration table has various pieces of information in it such as a pointer to RAM, how much RAM is available at that location, etc. Also, ADVANCE can run correctly anywhere in the target microcomputer's decoded address space, except over the 68000 interrupt vectors, etc. _________________________________________________________________ * System designers pay dearly in terms of system efficiency for the ability over-control tasks. On most mainframes not many people care about the very small amount of time it takes to load individual times for individual tasks in a task time-out timer. This occurs during the dispatch of each and every active task in a mainframe's dynamic process queue. In an embedded micro- processor in a missile, on its way to its target, many people care. Constantly processing a task's relative priority in ever- changing, real-world conditions is inefficient in many processes. Just when everybody is sure of the exact priority of each of 20 tasks, a low priority, error recovery task desperately needs scheduling. The system fails because not enough testing was done to determine that the prioritys were not correct for an instant in time. Extensive stack checking, dynamic task-prioritization, and special time-slicing add up to 200+% extra processing time per task switch. A more efficient design methodology is based upon the ADVANCE OPERATING SYSTEM's "Balanced System Design" where tasks are assigned equal priorities (see section 1.6). Sometimes it is too late to do anything meaningful about speeding up a system once all the code is in place. Quite often the problem with real-time, multitasking applications is not just the application code but the operating system "kernel." Once system designers realize that the application code cannot be optimized further they look at the operating system wishing they had left out all non-essential features. Once an application is written it becomes exceedingly hard to trim code from the multi- tasking operating system kernel. Copyright (C) 1986, 1987 by Creative Software Technology 1-3 Advance Operating System Chapter 1 1.1 GENERAL FEATURES 1.1.1 MULTITASKING CAPABILITIES ADVANCE was designed to be used in real-time controllers. Therefore, multitasking software "overhead" has been trimmed to a minimum. This trimming in no way decreases performance, however, and many powerful functions are available to the applications programmer. ADVANCE allows the engineer at assembly time to select either multitasking or straight-line processing. He can easily change the number of modules while debugging his program, or even go back to straight-line processing. One process can even turn on or off another concurrent process. 1.1.2 MODULAR ARCHITECTURE Figure 1-1 depicts the -------------------------- structure of ADVANCE. The | Advance | system resides in a 4K kernal. | Operating | Parallel tasks, or modules, | System | are simply plugged into place | -------------------- | as they are needed. This | | ERI | | modular scheme allows the ap- | -------------------- | plications engineer to solve | -------------------- | problems involving complex, | | TASK #1 | | parallel control processes. | ------ ------ | During the design period, he | | | | simply divides machine tasks | ------ ------ | by location and function into | | TASK #2 | | individual processes. He can | ------ ------ | then quickly spot parallel | | | | processes and separate them | ------ ------ | into simple modules. | | TASK N | | | -------------------- | The Error Recovery Inter- | -------------------- | face (ERI) software is part of | | IDM | | a supervisory module, shown | -------------------- | here to illustrate the entire | | ADVANCE fault tolerant system. -------------------------- Fig. 1-1 Structure of ADVANCE Copyright (C) 1986, 1987 by Creative Software Technology 1-4 Advance Operating System Chapter 1 1.1.3 TASK COMMUNICATION ADVANCE supports an inter-task communication system. Three basic functions control a powerful message passing technique. The "mailbox" system is designed to work well with high level language design. The internal ADVANCE "post office" software organizes all task mailboxes. Some tasks may want to be turned on only if they receive a message from a particular task. ADVANCE checks to see if the calling task is the one that the receiving task wants to be activated for. If the receiving task is not active, and wants to be activated by a certain task, ADVANCE activates the target task. Each application task has complete control over its mailbox. If a task must wait for a command from another task in order to execute some code, for instance, they can de-activate themselves until they get "command" mail from another task. If a task can run without waiting on an external command message, ADVANCE lets the task monitor its own mail flag for new "letters" while the task does some other processing. Also, individual task mailboxes can each hold from a single message pointer to as many message pointers as there are registered tasks. A task can have many mailboxes, one registered mailbox active at any time. 1.1.4 REAL-TIME CONTROL Unlike some multitasking systems that claim to run "real- time," the ADVANCE OPERATING SYSTEM services real-time events with tremendous speed. Fast and efficient control of peripheral devices by a computer depends on the wise use of interrupt pro- gramming. Most systems available on the market today take two to ten times longer than ADVANCE to do simple task switching. ADVANCE's dispatcher can change environments (do a task switch) on an 8-MHZ 68000-based system in less than 80 microseconds. Most popular 8-bit or pseudo 16-bit microprocessors (running at 1 MHZ) using ADVANCE will typically service each module of a six- module program once every 750 microseconds. This estimate is based on the average piece of production machinery equipped with ADVANCE task-switching algorithms on the field right now. A faster processor, of course, will respond even more rapidly. This type of performance means that your processor can run sev- eral concurrent tasks and directly operate stepping motors -- even manage sensor-driven mechanical equipment -- without a slave processor. This means much savings in hardware expense. Copyright (C) 1986, 1987 by Creative Software Technology 1-5 Advance Operating System Chapter 1 1.1.5 EASY MAINTENANCE Because the ADVANCE OPERATING SYSTEM is modular, engineers can break large functions into smaller modules. Huge, complicated tasks that normally end up being impossible for the user to understand are broken down into logical partitions. These smaller sections are naturally easier to understand and maintain for the entire useful life of the application. This means much lower maintenance costs for the end-user, a valuable selling feature in product bulletins. 1.1.6 HIGHER EFFICIENCY For several reasons ADVANCE-operated equipment has higher throughput. Many serial processes can "overlap" each other or even run concurrently in a multitasking operating system. This restructuring speeds up the overall process significantly. The concurrent processing feature works together with the optional Error Recovery Interface (ERI) feature to smooth out erratic process variables. These two features, combined together, pro- duce economical machine operation (such as scheduling small errors into a more timely preventative maintenance schedule). 1.1.7 HARDWARE SIMULATION SUPPORT ADVANCE is structured so that the programmer can make a model of the final application environment, running the actual software but simulating hardware events on the diagnostic terminal. Real hardware bugs thus become easy to locate during integration testing. Critical timing paths of complex processes can be simulated prior to actual mechanical movement. This simulation helps to protect machinery from damage from software errors during debugging. 1.1.8 FIELD-TESTED The ADVANCE OPERATING SYSTEM is working in the field today, with thousands of hours of run time on it already. Original ADVANCE OPERATING SYSTEM components, such as the dispatch system, Error Recovery System, Interactive Diagnostic Module, etc., have hundreds of thousands of hours of actual run-time in a variety of process-control applications. This code has also been tested and used in medical imaging equipment, telecommunications systems, data acquisition systems, educational systems, and video games. Most engineers now using the original ADVANCE software components are very impressed by its efficiency. Machine "down-time" is significantly reduced. Combinations of asynchronous errors that could not be planned for are smoothly and quickly corrected. Repair crews appreciate this system because it corrects most intermittent errors in ADVANCE-operated equipment unless they become mechanical or electrical "hard" failures. Copyright (C) 1986, 1987 by Creative Software Technology 1-6 Advance Operating System Chapter 1 1.1.9 COMPARISON BETWEEN TWO OPERATING SYSTEMS Suppose we have to choose between two multitasking operating systems. Lets say that Brand A has similar features to Brand V. Both have task management, inter-task communication and synchro- nization, real time clock, memory allocation, and etc. Brand A does a task switch in less than 80 microseconds and Brand V does a task switch in 106 microseconds. Brand V has more control over the switching of tasks at the expense of 26 microseconds of time. Suppose we have a multitasking application that incorporates 10 tasks, with any 5 of those tasks in the active dispatch queue at any given moment. How long will it take for the processor to stop processing a certain communication task, process the other tasks, and return to the original communication task? Let's use Brand A and Brand V for our analysis: Five Task Cycle Time = ( T1 + disp + T2 + disp + T3 + disp + T4 + disp + T5 + disp ) As you can see, the dispatch overhead is multiplied times the number of active tasks, in this case, five tasks. In Brand A we will get back to our original task 21us times the number of active tasks (over 100us) faster than Brand V. In many real-time applications an average task can do its average processing (using an 8 MHZ 68000) in 80us (or thereabouts). If we multiply 80us per task times 5 tasks we have 400us (plus dispatch time of say 85us times 5 tasks = 425us) plus 425us overhead. This totals to 825us cycle time for Brand A. Brand V would add over 100us baggage to every five-task cycle: T1 T2 T3 T4 T5 TOTALS: Process: 80 80 80 80 80 400us Switch tasks: 80 80 80 80 80 400us Total Brand A 5-task cycle time: 800us Brand V baggage: 26 26 26 26 26 130us Total Brand V 5-task cycle time: 930us In applications that are not as real-time intensive, such as a group of users on a mainframe, the extra "baggage" difference between the two brands is less significant. There are many multitasking operating systems, however, where you want to squeeze every microsecond you possibly can out of the processor: high-speed telecommunications, missiles, process control, real- time expert systems, etc. Many experienced system designers will sacrifice a little extra task control for a greater amount of improvement in system speed and efficiency. Copyright (C) 1986, 1987 by Creative Software Technology 1-7 Advance Operating System Chapter 1 1.2 AOS/68K ENTRY VECTORS There are four entry points into AOS. These entry points provide the necessary "hooks" into the ADVANCE OPERATING SYSTEM for user programs. There are some precautions that must be observed when using the major AOS/68K entry points. Here, then, is some very important information concerning these vectors. 1.2.0 Entry ZERO Entry ZERO is at the top of AOS. This is the starting location of AOS. The application's startup code simply jumps to the beginning of the 4K ROM to turn control over to AOS. The 68000 processor must first be in the supervisor state prior to jumping to AOS Entry ZERO. Provide a minimum of 256 bytes of system stack space for initialization and AOS system call usage. If there will be nested levels of interrupts then additional system stack space may be required. The minimum 256 byte ram requirement is in addition to the total ram specified in the configuration table parameter RAMSIZE (see section 1.4). 1.2.1 Entry ONE Entry ONE is where all AOS system calls are vectored. This location is exactly 1024 bytes from the beginning of AOS. You may enter Entry ONE via Motorola interrupt TRAP #1. In our example code we've vectored TRAP #1 to point to this location*. Please notice the general format for Entry ONE system calls: MOVE.L #MAIL_BOX,A0 MOVE.L POSTBX,D0 TRAP #1 1.2.2 Entry TWO Entry TWO is the simple dispatcher. This location is exact- ly 2048 bytes from the beginning of AOS. Entry TWO is entered via some interrupt. In some of our example application code we used TRAP #0 to point to this location in order to reschedule tasks. When we wanted to release the processor, we simply executed a TRAP #0 instruction which caused a rescheduling of active tasks on a round-robin basis. If you have a simple square wave pulsing into a 68000 hardware interrupt at 500 microsecond intervals, for example, you can "time-slice" by pointing this interrupt vector to Entry TWO. Your dispatch timer must be automatic. There is no provision in Entry TWO for reloading a time-slice timer. There is no provision in Entry TWO for execut- ing any special user code in the middle of the dispatch. For high-speed applications, use Entry TWO for fast, simple dispatch- ing. Use Entry THREE for special dispatch service. Copyright (C) 1986, 1987 by Creative Software Technology 1-8 Advance Operating System Chapter 1 1.2.3 Entry THREE Entry THREE is located exactly 3072 (3K) bytes from the beginning of AOS, is essentially the same as Entry TWO with one important exception. If the user supplies a non-zero address in the auxiliary dispatch vector (see configuration table parameter "AUXDSP") AOS will hop off to the location pointed to by AUXDSP right in the middle of the dispatcher. This concept allows an application to restart some dispatch interrupt timer right in the middle of the dispatch service. The user-supplied AUXDSP routine can change any register but A7. The system stack pointer, A7, must be preserved by the user-supplied AUXDSP routine. Obvious- ly, Entry THREE dispatch service is not going to be quite as fast as our simple, Entry TWO dispatch because of the AUXDSP proces- sing. Choose either Entry TWO or Entry THREE for your reschedu- ling of tasks, whichever one that best suits your application. 1.3 Interrupts AOS/68K, from version 1.04 and on, saves individual system stack pointers on each user stack. This change was made to handle multi-level, nested interrupts from within task exception processing. Versions before 1.04 kept the same system stack pointer for all tasks. The previously undefined DATAPTR must now point to how much system stack space is required per task. See the parameter "DATAPTR" in chapter 1 of this manual for details. The AOS/68K 4K kernel MAKES NO TRAP CALLS whatsoever. You may use whatever trap vectors you have available to point to the AOS/68K entry vectors listed above. If your 68000-based machine already has trap 0, 1, and 2 in use, no problem, use trap 3, 4, and 5, or whatever trap vectors you have available. AOS/68K does not have to be modified. The AOS/IDM, however, uses specific traps (trap #0, trap #1, and trap #2) to hook into the ADVANCE OPERATING SYSTEM kernel. The IDM, with the exception of the Trap calls, is position and device independent. For a limited time, Creative Software Technology will ship the IDM source code to companies that pay IDM's list price. You may change the trap numbers to whatever trap numbers your system needs. For those companies that register AOS/IDM with CST, CST will do the change for you at no additional cost. Copyright (C) 1986, 1987 by Creative Software Technology 1-9 Advance Operating System Chapter 1 1.4 CONFIGURATION TABLE The ADVANCE OPERATING SYSTEM is position independent and occupies a 4K ROM space in the target microcomputer's memory, just in front of a user-supplied configuration table. Figure 1-1 shows the basic structure of the configuration table. The table is composed of two major parts. The first part is the configura- tion table "header." The second part consists of from one to ten-thousand static task control block "cells." An individual static task control block cell is composed of seven pieces ( 28 bytes ) of information. As soon as your system software architect decides upon the maximum number of tasks that will be needed, populate a cell for each task that is to be registered with ADVANCE. These cells are used by ADVANCE to form the various high-speed system data struc- tures, including stack space for each task. Only in rare circum- stances should an application ever need to register more than five to ten task cells. It is nice to know, however, that ADVANCE can manage more tasks than most applications will ever need. --------------------- $XX00 | HEADER | ===================== $XX20 | TASK 1 | |---------------------| $XX3C | TASK 2 | |---------------------| $XX58 | TASK 3 | |---------------------| $XX74 | TASK 4 | |---------------------| $XX90 | TASK 5 | . . . . . . |---------------------| | TASK N | --------------------- Figure 1-2 Configuration Table Copyright (C) 1986, 1987 by Creative Software Technology 1-10 Advance Operating System Chapter 1 1.4.1 Configuration Table Parameters The ADVANCE OPERATING SYSTEM uses both stack structures and non-stack structures. Whenever AOS uses stack structures the user manual will identify them as such. Stack structures, such as the AOS mailbox structure, are put into memory backwards from the way the static configuration table organizes parameters. The configuration table parameters discussed below, are placed in memory in numerical order. If parameter VALID is located at $B000, then RAMPTR will be located at $B004, RAMSIZE will be located at $B008, etc. --------------------- $XX00 | V L I D | |---------------------| $XX04 | RAMPTR | |---------------------| $XX08 | RAMSIZE | |---------------------| $XX0C | AUXRST | |---------------------| $XX10 | AUXDSP | |---------------------| $XX14 | SERVPTR | |---------------------| $XX18 | DATAPTR | |---------------------| $XX1C | NTASKS | --------------------- Figure 1-3 Configuration Table Header _________________________________________________________________ -SPECIAL NOTES -- The letters "T.B.D." stand for "to be defined," meaning that the parameter associated with "T.B.D." is not defined in this release of the user manual. We are expanding the functionality of the ADVANCE OPERATING SYSTEM and have included certain pointers for upward compatibility with future releases. Copyright (C) 1986, 1987 by Creative Software Technology 1-11 Advance Operating System Chapter 1 struct TOP This structure is the configuration table. AOS needs to know certain things about the application code. This structure, placed just behind AOS in the 68000 memory map, is the vital link between AOS and the application program. If AOS were to be placed at $A000, for instance, then this structure needs to be at $B000. The ADVANCE OPERATING SYSTEM is position independent. AOS will work correctly placed almost anywhere in the 68000 address space. Naturally, of course, AOS cannot run correctly if it is placed over top of the exception vector table. VALID BYTE 'VLID' AOS examines this location in order to see if a valid user program is in memory. If the ASCII capital letters "VLID" are the first 4 bytes in the configuration table, then AOS "turns on." If VLID is not at this location then the program halts. This feature is used primarily during ram debugging. If for any reason an application "leaves" a ram environment (power interrup- tion, etc.), AOS tries to detect it and will not jump to an invalid application if the "VLID" signature is not present. RAMPTR LONG $2000 This points to application RAM. AOS uses this RAM for stack files, task stacks, tables, lists, data structures, and system variables. In our assembly language example we are telling ADVANCE that there is ram available starting at location $2000. RAMSIZE LONG $2500 This is the amount of application RAM that is available at location RAMPTR. The formula for determining how much ram to set aside for AOS is: 48 * number of tasks plus $100 bytes plus total requested stack size = required RAM. In our example we are telling ADVANCE that there is $2500 bytes of ram available starting at location RAMPTR. AUXRST LONG $0000 This is the auxiliary reset routine. Just after AOS sets up the system stack pointer, the AUXRST vector is examined. If AUXRST is a non-zero value then AOS jumps to subroutine AUXRST in order to execute user reset code. In our example we are telling ADVANCE (by the presence of the $0000 at vector AUXRST) that we do not have any other special reset code that has to be executed. Copyright (C) 1986, 1987 by Creative Software Technology 1-12 Advance Operating System Chapter 1 AUXDSP LONG $0000 This is the auxiliary dispatch routine. If the application uses Entry THREE dispatch code in order to reschedule tasks, then AOS dispatch code examines this location. If AOS detects a non- zero value at this location, then AOS jumps to subroutine AUXDSP in the middle of the normal dispatch service before the next active task is scheduled. Address register A3 points to the address of the configuration table and address register A4 points to the beginning of system ram before the call to AUXDSP is made. The user-supplied AUXDSP routine does not have to save A3 or A4 but must return from subroutine in the system state (the same state in which the processor was in prior to the AUXDSP call). In our example we are telling ADVANCE (by the presence of the $0000 at vector AUXDSP) that we do not have any other special dispatch code that has to be executed during the dispatch service. If you are vectoring your dispatch service to the simple dispatch version at Entry TWO then ADVANCE does not even check vector AUXDSP (auxiliary dispatch service is not available with the Entry TWO dispatch service). SERVPTR LONG $0000 This is a pointer to ---------- ---------- the optional user sup- $XX00 | V L I D | --> | IN CHR1 | plied routines. The |----------| | |----------| ADVANCE OPERATING SYSTEM $XX04 | RAMPTR | | | OUT CHR1 | looks at the SERVPTR vec- |----------| | |----------| tor itself before it | RAMSIZE | | | KYSTAT1 | examines the table of |----------| | |----------| pointers that SERVPTR | AUXRST | | | TRNSTAT1 | points to. If the |----------| | |----------| SERVPTR vector is equal | AUXDSP | | | IN CHR2 | to a $00000000 then no |----------| | |----------| further processing is $XX14 | SERVPTR | -- | OUT CHR2 | performed for any calls |----------| |----------| to the following rou- | DATAPTR | | KYSTAT2 | tines. The ADVANCE OP- |----------| |----------| ERATING SYSTEM kernel $XX1C | NTASKS | | TRNSTAT2 | (part one, not the IDM) |----------| |----------| does not use any of the $XX20 | TCB #1 | | USR VEC1 | service routines unless |----------| |----------| the user-written applica- $XX3C | TCB #2 | | USR VEC2 | tion makes a call to a |----------| |----------| user supplied vector. : | USR VEC3 | AOS will recognize the 16 |----------| : routines that SERVPTR | TCB #N | : points to if the vectors ---------- |----------| do not contain address | USR VEC8 | $000000. ---------- Figure 1-4 User-Supplied Routines Copyright (C) 1986, 1987 by Creative Software Technology 1-13 Advance Operating System Chapter 1 The first eight vectors are reserved for AOS user-supplied IDM support calls. The second eight vectors are reserved for additional user-supplied routines. The Interactive Diagnostic Module (IDM) uses the first four vectors to operate most of the IDM commands. One IDM command, though, called LINK, needs to link together a user-supplied port number 1 to a second user- supplied port number 2. All other IDM commands use only the following first four vectors. The first eight vectors that SERVPTR points to are as follows: 1) in_character_p1 routine: The IDM (Interactive Diagnostic Module) will jump to subroutine in_character_p1 to get data and diagnostic commands. Subroutine in_character_p1 preserves all registers except D0. Upon return from subroutine in-charac- ter_p1, register A0 points to a long word where the low order byte contains a single ASCII piece of information from the sup- ported serial device. IDM makes a call to key_status1 before it makes a call to in_character_p1 so as to permit task-sharing. 2) out_character_p1: The IDM will jump to subroutine out_char- acter_p1 to output data to some user supplied output device such as a dumb terminal or another computer. Vector 2 (out_charac- ter_p1) preserves all registers. The low order byte in D1 will contain the single ASCII piece of information that is to be output to the user's output device. IDM makes a call to trn_status1 before it makes a call to out_character_p1 so as to permit task-sharing. 3) key_status1: The IDM needs to know if it is O.K. to make a call to in_character_p1. By definition the user-written in_char- acter_p1 hogs the processor until the character to be sent is actually sent. To help prevent any task from hogging the i/o device, user-written "key_status1" routine can be invoked to return the status of the output default i/o device, before a call to get_character_p1 is actually made. User-written code pre- serves at least registers A6 and A7. Whenever a call to key_status1 is made, the AOS/68K kernel will be returned one of the following two conditions: (1) C = 0: If the carry bit in the condition code register is set to 0 then there is no character ready to be received by making a call to "in_character_p1". (2) C = 1: If the carry bit in the condition code register is set to 1 then there is at least one character ready to be received by making a call to "in_char- acter_p1". 4) trn_status1: This routine returns the status of the output device. User-written trn_status1 examines the status register in the output device to see if the output port on the USART (or whatever device is currently being used) is ready to transmit a character. After a call to key_status1 the AOS kernel is re- turned the C bit in the condition code in one of the following two states: Copyright (C) 1986, 1987 by Creative Software Technology 1-14 Advance Operating System Chapter 1 (1) C = 0: If the carry bit in the condition code register is set to 0 then the output device is not ready to send a char- acter. (2) C = 1: If the carry bit in the condition code register is set to 1 then it is O.K. to make a call to put_char. If a call to out_character_p1 is made without first making a call to key_stat1, then the other tasks cannot task-share the CPU. 5) in_character_p2: (same as above but use port #2, etc) 6) out_character_p2: (same as above but use port #2, etc) 7) key_status2: (same as above but use port #2, etc) 8) trn_status2: (same as above but use port #2, etc) If your system will require AOS/IDM, and you must have task- sharing during character i/o, use the following table to make the necessary calls. To Call: Call This First: get_character_p1 key_status1 put_character_p1 trn_status1 Note: The ADVANCE OPERATING SYSTEM kernel does not need to use any of the user-supplied routines unless external (application) software makes a call to one of the user-supplied routines. If you have some other debugging methodology that does not require the AOS/IDM, then the AOS/68K kernel runs fine without the user- supplied, default i/o device routines. The IDM, at the time this manual went to press, uses only in_character_p1, out_charac- ter_p1, key_status1, and trn_status1. None of the other routines described in the SERVPTR section are being used by the IDM. The IDM will make use of the rest of the user-supplied routines in future versions of the IDM. Therefore, please supply at least the first four routines if you are planning to use the Interac- tive Diagnostic Module. Please see the code at the end of the user manual for examples on how to set up and use the first four user-supplied routines. DATAPTR LONG $0000 This is a pointer to a user supplied table of parameters. The first (and for now, only) parameter is a long word that contains the size of the system stack for each task. SS_SIZE parameter can be any value between 256 and 4096 ($100 and $1000). If the system designer forgets to set up this pointer and its associated stack value properly (not recommended), AOS/68K may allocate 256 bytes of system stack for each task. If the DATAPTR itself is a 0, then the system stacks for each task will default to 256 bytes of stack. If SS_SIZE is a value greater that 4096, then AOS/68K will use 256 as the size of the system stack for each task. Please reserve 256 bytes of system stack per task for AOS/68K. If your system needs system stack for it's application exceptions, then add the extra stack space to the $100 bytes of system stack that AOS/68K needs. Copyright (C) 1986, 1987 by Creative Software Technology 1-15 Advance Operating System Chapter 1 AOS/68K keeps separate system stacks (as well as separate user stacks) for each task. System stacks are kept together, separate from user stacks. All system stack sizes for each task will be the same. There is no way to define different sizes of system stack space for different tasks. If DATAPTR points to a long word that contains $500, for example, then each task will get $500 bytes of system stack. To set up the system stacks, initialize the system stack pointer to point to where you want the system stack area to be. Then jump to the beginning of AOS/68K (initially enter the AOS/68K kernel in the supervisor mode). Let's suppose, for example, that you entered AOS/68K with the system stack pointer equal to $1100. Say the system required $200 bytes of system stack for each of four tasks. AOS/68K will use the ram area from $1100 to $1900 for system stacks, and $100 bytes below $1100 for initial kernel stack usage*. Task #1 will have it's system stack pointer set to $1300. Task #2 will have it's system stack point- er initialized to $1500, task #3 stack pointer will be set up to $1700 and task #4 will have it's stack pointer set to $1900. NTASKS LONG $0005 This is the total number of tasks that the application is wanting to register. Just because there is 5 in this position does not mean that five tasks will become active. The tasks that the application wants to be made immediately active must be defined in the static task control block (table) as being ACTIVE in order to be placed in the active dispatch queue. AOS uses this number to initially set up all data blocks, including stacks, at reset time. AOS assumes that all registered tasks may become active at the same time and provisions are made to accommodate this situation. NOTE: At least one task must be active at all times in AOS/68K. Systems using AOS/68K can never have a machine state where all tasks are inactive at the same moment in time. ----------------------------------------------------------------- * (the exact system stack size needed below $1100 in this example, depends on the several factors, one of which is how much stack the AUXRST routine uses). If you are not sure how much stack below $1100 will be required, and you are tight on stack space, initialize $1000 to $1100 to a known value and do a few resets. Then examine the area from $1000 to $1100. Copyright (C) 1986, 1987 by Creative Software Technology 1-16 Advance Operating System Chapter 1 1.5 STATIC TASK CONTROL BLOCK struct TASK This is the static task control block. Information in this structure is used by AOS to set up various internal data struct- ures. If NTASKS is equal to five (5), then there must be five (5) static task control blocks that are similar in form to this one for each task. You can turn on the tasks at reset time or dynamically with the task_on system call. You must, however, register all possible tasks with AOS at system reset. AOS sets up stacks for all registered tasks at reset time just in case all of the tasks become active at the same time. Tasks that have static TCB parameter STATE set to ACTIVE (at RESET time) get placed in the active dispatch queue. Tasks that have TCB parame- ter STATE set to INACTV are not turned on at system reset. _______________ | | | | | $XX20 | STARTING ADR | --> PCTR |___|___|___|___|_______________ | | | | | | | | | $XX24 | T | A | S | K | N | A | M | E | |___|___|___|___|___|___|___|___| | | | | | $XX2C | S T K S I Z E | |___|___|___|___| | | | | | $XX30 | EDC TBLE PNTR | |___|___|___|___| | | | | | $XX34 | U S R P A R | |___|___|___|___| | | | $XX38 | STATE | |___|___| | | | $XX3A | TSKNO | |___|___| Figure 1-3 Task Control Block PCTR LONG #MOD1 This is the initial transfer vector for a registered task. When this task is next in the dispatch queue program control is turned over to this location whenever a task is scheduled for the first time. NAME BYTE 'Mod XXXX' This is the 8-byte ASCII name of the task. The name assists in the routine debugging of a program whenever the optional diagnostic software is running concurrent with the user's application program. Copyright (C) 1986, 1987 by Creative Software Technology 1-17 Advance Operating System Chapter 1 STKSIZE LONG $400 This is the amount of stack that this task needs. The limit to the amount of stack that a task can have is based upon the total amount of ram that this task, and the other tasks will require. The application engineer needs to allow enough stack space for each task to execute properly. AOS, for speed purposes, does NO stack-checking. Be sure to allow plenty of stack for each task. Later on, when the code is debugged, optimize the task stacks. EDCTBLE LONG $0000 This is a pointer to this task's Error Recovery table. Please make this vector equal to $000000 for the time being in order to be upward compatible with future releases of AOS. The features to be found in our optional ERI software will generally make a significant improvement in the speed, efficiency and reliability of the applications progam. USRPAR LONG $0000 This is a pointer to user supplied parameters. (T.B.D.) STATE WORD ACTIVE This is a 2-byte flag that tells AOS if this task is to be made active or not active. If the value here is ACTIVE (any non- zero value) then this task is placed in the active dispatch queue. TASKNO WORD TASK This is the "I.D." number of this task. Any number from 1 to 65,535 is considered by AOS to be a valid task identification number. Parameter TASKNO does not relate to a task's dispatch priority. A large or small number in this location has no affect on the relative importance of a task as far as AOS is concerned. Although the user can initially order the dispatch sequence, ADVANCE will very probably change the order of the dispatch as soon as any one of several system calls are made. For example, turning off and on the same task will take the task out of wherever it was in the dispatch queue when the task is turned off and place the task at the end of the dispatch queue whenever it is turned back on again. If this turning off and on again of the same task is interspearsed with other system calls there is always the remote possibililty that the task, whenever it is turned back on again, will find itself back in exactly the same, original dispatch position as it started out from. Copyright (C) 1986, 1987 by Creative Software Technology 1-18 Advance Operating System Chapter 1 1.6 TASK PRIORITIES Please do not depend upon prioritization by task numbers or a certain dispatch sequence in the design of your application code if you plan on using system calls such as "delay," "tsk_on," "tsk_off," etc. Task numbers have nothing to do with task prior- ities. The ADVANCE OPERATING SYSTEM is designed to run sophisti- cated error recovery software which does not permit unequal task priorities. Temporary task prioritization may be achieved, how- ever, by letting "important" tasks make system calls which do not permit rescheduling of tasks. Rescheduling of tasks from system calls is disabled by setting a certain bit true in AOS system command words. The ADVANCE OPERATING SYSTEM uses the Balanced System Design where all tasks are assigned equal priorities (see section 1.6). Also, please make a note of the fact that two special task numbers are reserved by the ADVANCE OPERATING SYSTEM. These two special reserved task numbers are: -1 ($FFFF): This number is put into a registered task's mailbox ( in the "SENDER" parameter ) whenever it receives a message from some interrupt routine. Interrupt routines are normally not "tasks" and as such are not assigned task numbers. Since an interrupt can send a message to any task, however, a -1 clearly indicates the origin of the message in a task's mailbox (see AOS system call post_box in chapter 2). "ID": The ASCII characters "ID" ($4944) are reserved for use as the task number of the Interractive Diagnostic Module. Please do not use $4944 as a task number for any user-registered tasks. If you are going to be using the IDM for debugging purposes, please place the characters "ID" in the corresponding task number location in the configuration block associated with the IDM transfer vector, etc. Copyright (C) 1986, 1987 by Creative Software Technology 1-19 Advance Operating System Chapter 1 1.7 TASK STATES The ADVANCE OPERATING SYSTEM puts registered tasks into one of three states. A registered task is a task that has been defined in the Configuration table with a static task control block. The three states are INACTIVE, ACTIVE, and EXECUTING. The three states are as follows: INACTIVE <----------> ACTIVE <----------> EXECUTING INACTIVE: An inactive task is defined to be any registered task that is not in the process queue (sometimes called the dispatch queue). This task is said to be "off," or inactive. The stack associated with this inactive task is preserved for as long as power is applied to the computer. ADVANCE does not permit permanently turning off a task so as to free up his stack space for other tasks. ACTIVE: An active task is defined to be any registered task that is in the process queue (sometimes called the dispatch queue). The task is ready to be dispatched so as to continue from wherever it was executing code before the last task switch. Tasks currently scheduled to run in a process queue in a multi- tasking operating system seem as if they are all active at the same time. Technically speaking, of course, there is only one active task at time in a single microprocessor design. The system gives the impression that a group of tasks are active, while another group of tasks are inactive. EXECUTING: An active task that is currently using the processor's program counter, internal registers, etc. System call tsk_on, for instance, puts a task into the dispatch queue. This does not mean that the task just turned "on" is going to be instantly placed in the EXECUTING state. It is simply in an ACTIVE state, ready to be placed in a EXECUTING state. System call tsk_off takes ACTIVE tasks (sometimes EXECU- TING tasks) and puts them in the INACTIVE task state. For as long as logic power is supplied to the microcomputer, the stack area for the inactive task remains untouched by the operating system. The INACTIVE task can be turned on again (placed in the ACTIVE state) by making a call to tsk_on. The task just activated gets his untouched stack space back again. Copyright (C) 1986, 1987 by Creative Software Technology 1-20 Advance Operating System Chapter 1 1.8 THE BALANCED SYSTEM DESIGN The Advance Operating System is based upon the Balanced System Design concept. In the Balanced System Design, each task in a multitasking system is given an equal amount of functionality. To explain the Balanced System Design it is helpful to describe an unbalanced system design first. In an unbalanced multitasking system tasks are assigned an unequal amount of responsibility. If an error occurs in a "top heavy" task, one that has more than it's share of functionality, the whole application suffers. Resources may be unnecessarily tied up by the errant task. Small tasks with (a few functions and) artificially high priorities can also cause resource problems, especially whenever they try to correct for run-time errors. Also, since functions are not evenly distributed throughout the system architecture, tasks are forced to arbitrarily and artificially change their priorities to make up for a lop-sided design topology. Asynchronous errors are difficult to correct for in such unevenly designed systems. What is a Balanced System? In a balanced multitasking system each task has an even amount of functionality. Why use a Balanced System? Balanced Systems are generally more efficient than unbalanced systems because they share system resources more evenly, and they share the work load more evenly. No single task can tie up the whole system indefinately. A Balanced System is also more fault tolerant. Expert System inference engines can run recovery algorithms with the assurance that they will probably be executed, not locked out by a instaneous priority lock-out problem. The net effect of balancing functions is that many former "fatal" errors are now not "fatal." If a task discovers a cor- rectable run-time error in a Balanced System, the other tasks can usually run for a short amount of time. This grace period gives the errant task, by authority of a supervisory task which moni- tors the state of the system process, enough time to correct the error. By spreading the functionality evenly over several tasks you can therefore avoid shutting down the system for many former "fatal" errors ( please refer to chapter four for a detailed description of the Balanced System error recovery techniques). How do you design a Balanced System? The steps necessary to design a Balanced System are: 1) Write down on a large piece of paper all of the functions that the system is supposed to do. 2) On a second piece of paper in a time-line format, using the first piece of paper as a reference, group all of the system functions in such a way as to show the functions that can happen concurrently. There are rare situations where you will not be able to spot any concurrent functions. For our example, assume we have a need for concurrency. Copyright (C) 1986, 1987 by Creative Software Technology 1-21 Advance Operating System Chapter 1 3) On the same piece of paper (or on a third sheet of paper) evenly distribute logically-related functions into a small number of tasks. Be quite sure that all of the tasks assigned by this process can really do work concurrently. Two logically related, serial processes can be grouped into the same task. Please do not make two logically related, serial processes into two tasks. Use geographical partitions to assist you like data aquisition, data processing, data output, etc., or, the front loader section of the machine, the testing section of the machine, the sorting section of the machine, etc. 4) Finally, geographically or in some other logical way, assign high priority asynchrounous events (hardware interrupts) evenly to tasks with related functionality. When you have finished your system design, leave it for awhile. Go get some- thing to drink, relax, or whatever. Later on, with a clear mind, review your design again. Talk it over with someone else. If you do not feel comfortable with your design, rework it again a few times until your are sure that system functions are distrib- uted as evenly as possible among all of the tasks. Copyright (C) 1986, 1987 by Creative Software Technology 1-22 2.0 ADVANCE OPERATING SYSTEM CALLS (Part One) 2.0.1 User Mode verses System Mode Special Entry Considerations For All System Calls: There are two major entry conditions for AOS system calls: entry from user mode and entry from system mode. Some AOS system calls work for both conditions. Please take time to read through the system command specifications before you make any system calls. As a general rule, making a system call from user mode means that a round-robin rescheduling of tasks will occur before a task returns to its code. Making a system call from within an interrupt, or from within system mode, however, will not cause a rescheduling of tasks before the calling task returns to its code. Please make a note of the fact that AOS system calls support one or the other entry conditions: entry from user mode or entry from system mode, and in some cases, entry from either mode. This design issue was addressed with the idea of supporting the majority of practical cases with the necessary flexibility. Let's examine some common situations: You can turn on or off any registered task from within the user mode. Suppose that one task monitors i/o events. This same task, from the user mode can turn on other tasks based upon sensor information. You can also turn on a task from within an application exception. An interrupt occurs and for practical reasons, such as the presence of a string sentinel character, you want to turn on a task to process the newly entered string. AOS system call tsk_on recognizes that the caller was in the system mode and turns on the requested task and returns immediately to the instruction just past the call to tsk_on. System call tsk_on, when invoked from the system mode, does not force rescheduling as it would have done if the call to tsk_on had originated from user mode. AOS system call tsk_off, however, must be entered only from the user mode, if it is expected to work correctly (this informa- tion is in the tsk_off specification). For most cases, a user will not want to turn off tasks from within an exception. Most of the time a task will get turned off while it is waiting for na event or message from another task. AOS supports turning off a task off in a few interesting ways. System call "receive" will turn off the calling task until the task receives a message from some requested task as specified by the task's id number. If a management task decides to terminate a task he can do this also by making a call to tsk_off from within the user mode. System call "delay" supports turning off a task also. When a task wants to delay for a time, it is turned off automatically until the delay counter reaches zero. The task is then turned on again. Copyright (C) 1986, 1987 by Creative Software Technology 2-1 Advance Operating System Chapter 2 2.0.2 System Register Parameters ADVANCE system calls have other common features. When a system command detects an error condition, address register A1 is used to point to a four byte register that returns status infor- mation from the system call. The calling task's A1 register itself is returned to the caller unchanged. If a task wants to turn on a task, it must do one of two things with register A1: 1) Set address register A1 equal zero (0). After the caller returns to his code (from making a system call) he'll notice that A1 and the data A1 points to are not changed. If a task does not care if an error occurs, then set A1 to equal zero. 2) Point A1 to some status long word other than address location zero. If a system command defines certain errors that can occur, then just after a caller returns to his code (from making a system call) the long word that A1 points to will be written to with either a pre-defined error code or $00. The error code is a number less than $80. The long word that A1 points to will be set equal to zero whenever no errors are detec- ted in the execution of the system command. Address register A1 is not changed. Make a habit of always initializing A1 properly. Please remember set up A1 to one of the above two conditions. Please take the time to check each command for the correct use of register A1. Most system calls require that data register D0 be set up to equal the requested system command code. The AOS commands are each a long word in length. The essential command information, however, is frequently within bits 0 through 7 of the least significant byte of the least significant word: D0_CODE COMMAND $00000001 tsk_on $00000042 tsk_off $00000003 tsk_stat $00000044 tsk_id $00000048 post_box $00000009 send $0000004A receive $0000000B sendx $00000010 time_set $00000011 time_read $00000012 tick $00000053 delay $00000018 put_char $00000019 get_char $0000001A key_stat $0000001B trn_stat $00000020 gt_cpt $000000A1 g_stk $00000022 res_tsk Copyright (C) 1986, 1987 by Creative Software Technology 2-2 Advance Operating System Chapter 2 Bit 7 of the command word has special significance. By setting bit 7 true on the following AOS/68K commands ( set bit seven = 1 ), you have another list of AOS commands that do essentially the same thing as the original, similar commands without bit 7 set true. Setting bit 7 = 1 is designed to let the calling task return to his code, just past the trap #1 call, without causing a re-scheduling of tasks. This function is useful for a lot of reasons. One such reason would be to see if another task is active at a particular moment in time. Setting bit 7 true on some commands, however, is not recommended. Tasks making calls such as "receive" for instance, would not want to return back to their code until they get a message from the calling task. The illegal "rq_" (return quick) version of AOS/68K command "receive" would give unpredictable results. AOS/68K special Return Quick commands, prefixed with a "rq_", are as follows: D0_CODE COMMAND $00000081 rq_tsk_on $00000083 rq_tsk_stat $000000C4 rq_tsk_id $000000C8 rq_post_box $00000089 rq_send $00000090 rq_time_set $00000091 rq_time_read $00000092 rq_tick $00000098 rq_put_char $00000099 rq_get_char $000000A2 rq_res_tsk Other registers may have to be set up prior to making each system call. Check the command description for the command you are intending to use for information on register parameter usage. Many of the program examples in this manual use position indepen- dent, stacked parameters. Appendix B shows many assembly lan- guage, position independent, parameter examples. Using position independent code is not required, however. Copyright (C) 1986, 1987 by Creative Software Technology 2-3 Advance Operating System Chapter 2 2.1 AOS System Command Specifications PLEASE NOTE: The following system commands in chapters two and three show how to use the system calls from "C," for formal parameter clarification purposes only. For example: TYPICAL USAGE: tsk_on ( motors, &status ); We are not including an interface library with the base section one. If we have an interface library available for your compiler we will make it available to you at a small additional charge. Please use the code examples in the "ASSEMBLY INTERFACE" for designing assembly language programs. Example: NAME: tsk_switch DESCRIPTION: Tsk_switch is the programmer's way to release the processor voluntarily. Tsk_switch causes a rescheduling of the next task in the dispatch queue. The current task's environment is saved on the current user stack while the next task in the dispatch queue is dispatched. If the regular timer interrupt dispatch is sometimes not quite often enough for certain applications, use tsk_switch to reschedule processes more rapidly. Tsk_switch is also used in many system designs to replace the need for a regu- lar timer interrupt type of forced rescheduling. Whenever "time- slicing" is not used, tsk_switch is placed in the inside loop of all program loops that would "hog" the processor for longer than, say, 200 microseconds. ENTRY CONDITIONS: User Mode only. TYPICAL USAGE: tsk_switch(); ASSEMBLY INTERFACE: TRAP #0 PARAMETERS: None. REGISTERS CHANGED: None. CAVEATS: AOS/68K tasks that service exceptions, upon entering the supervisor state, must lock out interrupts as their first in- struction. A time-slice timer must not be allowed to initiate a round-robin rescheduling of tasks while one task is in the super- visor state. Why? The AOS/68K task switch routines do not save the supervisor stack pointer on the user stack. If a task switch is allowed while one task is in the supervisor state, important data (like return addresses) can be lost on the supervisor stack. RETURN VALUES: None. Copyright (C) 1986, 1987 by Creative Software Technology 2-4 Advance Operating System Chapter 2 NAME: tsk_on DESCRIPTION: Use tsk_on to turn on any registered inactive task. The calling task sets up three parameters: 1) the i.d. number of the task he wants to turn on, 2) the address of a status word, and 3) the command word. ENTRY CONDITIONS: User Mode or System Mode. TYPICAL USAGE: tsk_on ( motors, &status ); ASSEMBLY INTERFACE: LINK A6,#-PARAMETER_TABLE LEA.L -STATUS(A6),A1 MOVE.L #TSK_ON,D0 MOVE.L #TASK4,D1 TRAP #1 TST.L (A1) BEQ.S NO_ERROR BSR ERROR_MSG A1 POINTS TO USEFUL ERROR DATA; NO_ERROR EQU $ PARAMETERS: D0 = command long word; D1 = target task; and A1 = pointer to status long word. REGISTERS CHANGED: None. CAVEATS: The newly activated task is added to the "bottom" of the present dispatch queue. The caller cannot place the newly acti- vated task "next" in the dispatch. RETURN VALUES: Parameter STATUS is reset to $00000000 if call to tsk_on is successful. Otherwise STATUS is set to one of the following error conditions, right justified within the long word: $01 : The task you tried to turn on is already on. $02 : There is no inactive task with that i.d. number. $03 : There are no active or inactive tasks*. $04 : There are no inactive tasks at the moment. *Although normally impossible, a system RAM problem could cause this rare error condition. Copyright (C) 1986, 1987 by Creative Software Technology 2-5 Advance Operating System Chapter 2 NAME: tsk_off DESCRIPTION: Use tsk_off to turn off any active task, including the task that makes the call. The calling task just sets up three parame- ters: 1) the i.d. number of the task he wants to turn off, 2) the address of a status word, and 3) the command word. If this command is entered from the system mode, which is not permitted, the target task is not turned off and a rescheduling of tasks does not occur. ENTRY CONDITIONS: User Mode only. TYPICAL USAGE: tsk_off ( solenoids, &status ); ASSEMBLY INTERFACE: LINK A6,#-PARAMETER_TABLE LEA.L -STATUS(A6),A1 MOVE.L #TSK_OFF,D0 MOVE.L #TASK4,D1 TRAP #1 TST.L (A1) BEQ.S NO_ERROR BSR ERROR_MSG A1 POINTS TO USEFUL ERROR DATA; NO_ERROR EQU $ PARAMETERS: D0 = command long word; D1 = target task; and A1 = pointer to status long word. REGISTERS CHANGED: None. CAVEATS: The task you just turned off looses his relative position in the dispatch queue. Even if it is turned back on again, it might not be dispatched in its original dispatch sequence. RETURN VALUES: Parameter STATUS is reset to $00000000 if call to tsk_off is successful. Otherwise STATUS is set to one of the following error conditions, right justified within the long word: $01 : The task you tried to turn off is already off. $02 : There is no inactive task with that i.d. number. $03 : There are no active or inactive tasks (a RAM problem). $04 : There are no inactive tasks at the moment. $05 : There is no registered task with that i.d. number. -1 : Illegal entry from system mode. Copyright (C) 1986, 1987 by Creative Software Technology 2-6 Advance Operating System Chapter 2 NAME: tsk_stat DESCRIPTION: System call tsk_stat returns the status of the requested task. A registered task can be in one of two basic states: on or off. ENTRY CONDITIONS: User Mode or System Mode. TYPICAL USAGE: tsk_stat ( communications, &tstatus ); ASSEMBLY INTERFACE: LINK A6,#-PARAMETER_TABLE LEA.L -TSTATUS(A6),A0 MOVE.L #TSK_STAT,D0 MOVE.L #TASK4,D1 TRAP #1 TST.L (A0) BEQ.S ITS_OFF BSR GET_STAT A0 POINTS TO USEFUL TASK STATUS; ITS_OFF EQU $ PARAMETERS: D0 = command long word; D1 = target task; and A0 = pointer to tstatus long word. REGISTERS CHANGED: None. CAVEATS: None. RETURN VALUES: Register A0 will point to a tstatus long word that contains one of the following bytes of information right justified within the long word: $00 : The requested task is currently not active $01 : The requested task is in the active state $02 : There is no registered task with that id number. Copyright (C) 1986, 1987 by Creative Software Technology 2-7 Advance Operating System Chapter 2 NAME: tsk_id DESCRIPTION: System call tsk_id returns the task id of the calling task. Sometimes a task will make a call to a general purpose subrou- tine. The subroutine may occationally need to know which task called it. The subroutine makes a "tsk_id" system call to deter- mine which task called it. The id of the calling task might be used as some type of index into a parameter table. ENTRY CONDITIONS: User Mode only. TYPICAL USAGE: tsk_id ( &tstatus, &status ); ASSEMBLY INTERFACE: LINK A6,#-PARAMETER_TABLE LEA.L -STATUS(A6),A1 LEA.L -TSTATUS(A6),A0 MOVE.L #TSK_ID,D0 TRAP #1 PARAMETERS: D0 = command long word; A0 = pointer to tstatus long word. A1 = address of STATUS long word. REGISTERS CHANGED: None. CAVEATS: None. RETURN VALUES: Register A0 will point to the long word equivalent of the task id of the calling task. The id is right justfied within the long word. The data that A1 points to will normally not be modified. If tsk_id is invoked from the system mode however, and register A1 does not contain a $00000000, then the long word that A1 is pointing to will contain a -1. Copyright (C) 1986, 1987 by Creative Software Technology 2-8 Advance Operating System Chapter 2 NAME: post_box DESCRIPTION: This call will post the address of your "mailbox" with AOS. Your post_box call will point to the "mailbox" on your stack frame (or static ram area). Every task wishing to use system functions "send" and "receive" must first post the location of its mailbox with ADVANCE. Figure 2-1 shows the structure of a task's mailbox when set up in a stack frame. A stack frame mailbox puts the parameters in memory from high address memory to low address 68000 memory. You may also set up your mailbox in a static ram area. Figure 2-2 shows that the stucture looks back- wards but is the same as Figure 2-1. In both cases the ADVANCE send and receive software expects the mailbox parameters to be organized as the relative hexadecimal offsets suggest. _____ | | | $XX1A MAIL FLAG |__|__| | | | $XX18 MAX LETRS |__|__|_____ ___________ | | | | | | | | | | $XX14 | SENDER #1 | $XX10 | PTR 2 MSG | |__|__|__|__| |__|__|__|__| | | | | | | | | | | $XX0C | SENDER #2 | $XX08 | PTR 2 MSG | |__|__|__|__| |__|__|__|__| | | | | | | | | | | $XX04 | SENDER #3 | $XX00 | PTR 2 MSG | |__|__|__|__| |__|__|__|__| Figure 2-1 Copyright (C) 1986, 1987 by Creative Software Technology 2-9 Advance Operating System Chapter 2 ___________ ___________ | | | | | | | | | | $XX00 | PTR 2 MSG | $XX04 | SENDER #3 | |__|__|__|__| |__|__|__|__| | | | | | | | | | | $XX08 | PTR 2 MSG | $XX0C | SENDER #2 | |__|__|__|__| |__|__|__|__| | | | | | | | | | | $XX10 | PTR 2 MSG | $XX14 | SENDER #1 | |__|__|__|__| |__|__|__|__| | | | $XX18 MAX LETRS |__|__| | | | $XX1A MAIL FLAG |__|__| Figure 2-2 ENTRY CONDITIONS: User Mode only TYPICAL USAGE: post_box ( &mailbox, &status ); ASSEMBLY INTERFACE: LOCALS EQU 0 EMPTY EQU 0 BOX EQU 4 This mailbox holds 4 letters; MSIZE EQU 8 ROM EQU $XXXX Set to point to ROM adr; ORG LOCALS A6LINK RMB 4 STATUS RMB 4 OPT SYS STATUS FLAG. RMB 2 MAILBOX FLAG. ML_FLAG EQU $-STATUS RMB 2 RESV SPACE 4 MAXIMUM MX_LTRS EQU $-STATUS NUMBER OF "LETTERS;" VOLUME RMB MSIZE*BOX RESERVE TOTAL MSG SPACE; PARAMS EQU $-STATUS COMPUTE STACK FRAME SIZ; MAIL EQU $-VOLUME BYTE SIZE OF MBOX; LETTERS EQU MAIL/4 MAX NUMBER OF LETTERS; Copyright (C) 1986, 1987 by Creative Software Technology 2-10 Advance Operating System Chapter 2 ORG ROM LINK A6,#-PARAMS RESERVE SPACE FOR MAIL; LEA.L -ML_FLAG(A6),A0 A0 <- ADR TASK #5'S MBOX; LEA.L -STATUS(A6),A1 A1 <- ADR OF STATUS LWORD; MOVE.W #EMPTY,-ML_FLAG(A6) ML_FLAG <-- 0; MOVE.W #LETTERS,-MX_LTRS(A6) MX_LTRS <-- MAX LETTERS; MOVE.L #POSTBX,D0 D0 <-- POST BOX COMMAND; TRAP #1 POST ADDRESS OF MAILBOX; PARAMETERS: D0 = command long word; A0 = pointer to caller's mailbox. A1 = address of STATUS long word. REGISTERS CHANGED: none CAVEATS: Mail consists of "letters." Letters consist of 4 bytes that contain the task number, or i.d. number of the sending task, right justified within the long word, and a pointer to the call- ing task's message, also one long word (4 bytes). The calling task is responsible for setting up the number of letters that his mailbox can hold. Each task's mailbox can hold as many letters as there are registered tasks, plus one. If the calling task does not set up mailbox parameter "MAX_LTRS," then one of two things may happen. 1) If the parameter is equal to 0, then ADVANCE considers this to mean that the receiving task does not want any mail delivered at the moment. A task sending a message to another task who set MAX_LTRS parameter = 0 will be returned an $07 code. 2) If parameter "MAX_LTRS" is greater than the total number of registered tasks, plus one, then ADVANCE will use the number of registered tasks, plus one, as parameter "MAX_LTRS" and ignore your mailbox MAX_LTRS parameter. When a task receives a letter, parameter "MAIL_FLAG" will be set to some non-zero value. It is the responsibility of the receiving task to clear parameter MAIL_FLAG to zero prior to making the "receive" system call. ADVANCE does not care what parameter MAIL_FLAG was before the mail is sent. The receiving task can also ignore parameter MAIL_FLAG if it wants to, however, it may be hard for the receiving task to determine if mail arrives. RETURN VALUES: If post_box is illegally entered from the system mode then if A1 does not point to $00000000, the data that A1 points to is set equal to -1. Copyright (C) 1986, 1987 by Creative Software Technology 2-11 Advance Operating System Chapter 2 NAME: send DESCRIPTION: If a certain task wants to communicate with another task, the calling task "sends" information ( a four byte pointer ) to the destination mailbox. The sending task need not know the address of the destination mailbox, ADVANCE knows the location of each task's registered mailbox. In order for "send" to work successfully, the target mailbox had to have been previously posted by the receiving task's "post_box" function call. System call "send" will also turn on the target task if the target task is inactive and waiting for a message from the call- ing task. See system call "receive" for more details. System call "send" can be invoked from the system mode as well as from the user mode. There are some differences, however. Send calculates the id of the task making the call to itself. If the call was made from the user mode, then the id of the task that made the call to send is placed in the receiver's mailbox. If the call to send was made from the system mode, then an id of -1 is placed in the receiver's mailbox. A task id of -1 is a sign, therefore, to the receiver that it has received a message from some interrupt service routine. If send is called from the system mode then a rescheduling of tasks is not performed. If send is called from the user mode, however, a rescheduling of tasks will occur. ENTRY CONDITIONS: User Mode or System Mode TYPICAL USAGE: send ( target_task, &message, &stat ); ASSEMBLY INTERFACE: LINK A6,#-PARAMETER_TABLE This example shows LEA.L -STATUS(A6),A1 a position indepen- MOVE.L #SEND,D0 dent status flag. MOVE.L #TASKNO,D1 MOVE.L #MSG,A0 TRAP #1 TST.L (A1) BEQ.S NO_ERROR BSR ERROR_MSG A1 POINTS TO USEFUL ERROR DATA; NO_ERROR EQU $ PARAMETERS: D0 = command long word; D1 = task to receive message; A0 = pointer to the calling task's message; and A1 = pointer to status long word. REGISTERS CHANGED: None. Copyright (C) 1986, 1987 by Creative Software Technology 2-12 Advance Operating System Chapter 2 CAVEATS: Task alpha, for example, can send many messages to task beta. System command send will place task alpha's task id in task beta's mailbox, along with a four byte pointer to some message. Task beta must read (process) the message and clear the task id in its mailbox. If task beta has cleared the task id slot ( that had alpha's task id in it) in its mailbox before task alpha sends another message to it, then the new message from task alpha is received with no problems and no error returns. On the other hand, if task beta has not cleared out task alpha's task id slot in beta's mailbox, then task alpha cannot send a second message to task beta successfully. RETURN VALUES: STATUS is set to $00000000 if the calling task successfully sends its message. If an error occurs, then STATUS is set to equal one of the following error conditions, right justified within the long word: $05 : Target Task has not registered his mail box location $06 : Unread mail from calling task in target task's mailbox $07 : No available message slots in target task's mailbox Because "send" occationally calls "tsk_on" there is a chance that one of these other errors codes will be returned: $01 : The task you tried to turn on is already on. $02 : There is no inactive task with that i.d. number. $03 : There are no active or inactive tasks. $04 : There are no inactive tasks at the moment. Copyright (C) 1986, 1987 by Creative Software Technology 2-13 Advance Operating System Chapter 2 NAME: receive DESCRIPTION: Each task knows the location of its mailbox. A task could easily monitor the mail flag "on" its mailbox for new mail. If the mail flag is set to some non-zero value a task could "open" the box and get its own "letter." System command "receive" lets a task shut off until it receives a letter from another task. This command initiates the turning on of the calling task once per call. Other tasks wanting to send mail to the receiving task will not keep trying to turn on the target task. The first (requested) task in with the mail turns on the receiving task. The other tasks wanting to send mail to the receiving task just drop off their letters via the system command "send." ENTRY CONDITIONS: User Mode only. TYPICAL USAGE: receive ( activator_task, &status ); NOTE - If activator_task = $00000000 then mail from any task will turn on the waiting task. If the activator_task = -1, then only a message from an interrupt service routine will turn on the waiting task. ASSEMBLY INTERFACE: LEA.L -STATUS(A6),A1 STATUS IS STACKED PARAMETER MOVE.L #RECEIVE,D0 MOVE.L #TASK3,D1 TRAP #1 PARAMETERS: D0 = command long word; D1 = activator task; A1 = pointer to status long word. REGISTERS CHANGED: None. CAVEATS: Mail consists of "letters." Letters consist of 4 bytes that contain the task number, or i.d. number of the sending task, right justified within the long word, and a pointer to the call- ing task's message, also one long word (4 bytes). The calling task is responsible for setting up the number of letters that his mailbox can hold. Each task's mailbox can hold as many letters as there are registered tasks, plus one. If the calling task does not set up mailbox parameter "MAX_LTRS," then one of two things may happen. 1) ADVANCE checks parameter MAX_LTRS prior to entry to system call receive. ADVANCE will not let a task enter system call receive if the calling task's MAX_LTRS parameter is equal to Copyright (C) 1986, 1987 by Creative Software Technology 2-14 Advance Operating System Chapter 2 zero. ADVANCE normally considers a MAX_LTRS parameter of 0 to mean that the receiving task does not want any mail delivered at the moment. If task ALPHA sends a message to task BETA, and if BETA has set MAX_LTRS parameter = 0, task ALPHA will be returned an $07 error code. 2) If parameter "MAX_LTRS" is greater than the total number of registered tasks, plus one, then ADVANCE will use the number of registered tasks, plus one, as parameter "MAX_LTRS" and ignore your mailbox MAX_LTRS parameter. The task's MAX_LTRS parameter is not changed by ADVANCE. Before a task makes a call to system call "receive," it should read any current mail in their mailbox. If a task has old mail in it's mailbox, it should clear the sender's TASK_NO, or ID to zero to indicate that the mail slot is empty. An emply mail slot can be re-used by ADVANCE for new mail. Its O.K. for a task to leave unread mail in its mailbox prior to its making a call to receive. ADVANCE, however, does not use mail slots with sender ids left in them. If a task has a lot of slots in its mail box tied up with sender ids in them, a task making a call to the task with the full mail box may not have a place to put new mail. When a task receives a letter, parameter "MAIL_FLAG" will be set to some non-zero value. It is the responsibility of the receiving task to clear parameter MAIL_FLAG to zero prior to making the "receive" system call. Before ADVANCE puts the call- ing task in the inactive state, ( from within the system call "receive" ), it checks to see if the caller's mail flag is set. If the mail flag is set then ADVANCE scans the caller's mailbox to see if the requested activator task has sent mail to the task that is making the call to system call receive. This action prevents a "deadlock" situation. ADVANCE's system call "receive" will sometimes return the caller to receive back to the instruction just past the TRAP #1 instruction, without placing the calling task in the inactive state. This occurs whenever the caller's mail flag is already set to some non-zero value and ADVANCE finds mail in the caller's mail box from the requested activator task. This also occurs whenever the caller's mail flag is already set to some non-zero value, there is a sender id in the caller's mailbox ( within the MAX_LTRS range ), and the caller's activator task is equal to 0. These situations are not defined as error conditions. RETURN VALUES: Parameter STATUS is reset to $00000000 if no errors are detected. Otherwise STATUS is set to one of the following error conditions, right justified within the long word: $06 : Calling task did not first register his mailbox. $07 : No activator task with given task ID number. $08 : Calling task's MAX_LTRS parameter = 0. -1 : Illegal entry from the system mode. Copyright (C) 1986, 1987 by Creative Software Technology 2-15 Advance Operating System Chapter 2 NAME: sendx DESCRIPTION: If a certain task wants to communicate with another task, the calling task "sends" information ( a four byte pointer ) to the destination mailbox. The sending task need not know the address of the destination mailbox, ADVANCE knows the location of each task's registered mailbox. In order for "sendx" to work successfully, the target mailbox had to have been previously posted by the receiving task's "post_box" function call. System call "sendx" will also turn on the target task if the target task is inactive and waiting for a message from the call- ing task. See system call "receive" for more details. System call "sendx" can be invoked from the system mode as well as from the user mode. There are some differences, however. Send (without the "x") calculates the id of the task making the call to itself. If the call was made from the user mode, then the id of the task that made the call to send is placed in the receiver's mailbox. If the call to send was made from the system mode, then an id of -1 is placed in the receiver's mailbox. A task id of -1 is a sign, therefore, to the receiver that it has received a message from some interrupt service routine. Sendx performs the same as Send but will not place a -1 as the task_id in the receiver's mailbox if it was invoked from the system mode. This is useful whenever a calling task finds itself in the system mode for whatever reason. The task that was in the system mode will want the correct id placed in the receiver's mailbox, not a -1 as system call "send" would have done in a similar situation. If sendx is called from the system mode then a rescheduling of tasks is not performed. There is no reason to invoke sendx from the user mode, as the application should use "send" for that mode. Sendx was made for special system mode cases. Remember, true hardware interrupt routines must use "send", not "sendx". ENTRY CONDITIONS: System Mode (User Mode not recommended) TYPICAL USAGE: sendx ( target_task, &message, &stat ); ASSEMBLY INTERFACE: LINK A6,#-PARAMETER_TABLE This example shows LEA.L -STATUS(A6),A1 a position indepen- MOVE.L #SENDX,D0 dent status flag. MOVE.L #TASKNO,D1 MOVE.L #MSG,A0 TRAP #1 TST.L (A1) BEQ.S NO_ERROR BSR ERROR_MSG A1 POINTS TO USEFUL ERROR DATA; NO_ERROR EQU $ Copyright (C) 1986, 1987 by Creative Software Technology 2-16 Advance Operating System Chapter 2 PARAMETERS: D0 = command long word; D1 = task to receive message; A0 = pointer to the calling task's message; and A1 = pointer to status long word. REGISTERS CHANGED: None. CAVEATS: Task alpha, for example, can send many messages to task beta. System command sendx will place task alpha's task id in task beta's mailbox, along with a four byte pointer to some message. Task beta must read (process) the message and clear the task id in its mailbox. If task beta has cleared the task id slot ( that had alpha's task id in it) in its mailbox before task alpha sends another message to it, then the new message from task alpha is received with no problems and no error returns. On the other hand, if task beta has not cleared out task alpha's task id slot in beta's mailbox, then task alpha cannot send a second message to task beta successfully. RETURN VALUES: STATUS is set to $00000000 if the calling task successfully sends its message. If an error occurs, then STATUS is set to equal one of the following error conditions, right justified within the long word: $05 : Target Task has not registered his mail box location $06 : Unread mail from calling task in target task's mailbox $07 : No available message slots in target task's mailbox Because "sendx" occationally calls "tsk_on" there is a chance that one of these other errors codes will be returned: $01 : The task you tried to turn on is already on. $02 : There is no inactive task with that i.d. number. $03 : There are no active or inactive tasks. $04 : There are no inactive tasks at the moment. Copyright (C) 1986, 1987 by Creative Software Technology 2-17 Advance Operating System Chapter 2 NAME: time_set DESCRIPTION: System call time_set is how to load the system "time" para- meter. Parameter time is also incremented by one every time a call is made to system call "tick." ENTRY CONDITIONS: User Mode or System Mode. TYPICAL USAGE: time_set ( time ); ASSEMBLY INTERFACE: MOVE.L #TIME_SET,D0 MOVE.L #TIME,D1 TRAP #1 PARAMETERS: D0 = command long word; D1 = time parameter; REGISTERS CHANGED: none. CAVEATS: none. RETURN VALUES: none. Copyright (C) 1986, 1987 by Creative Software Technology 2-18 Advance Operating System Chapter 2 NAME: time_read DESCRIPTION: This is how to read the system "time" parameter. ENTRY CONDITIONS: User Mode or System Mode. TYPICAL USAGE: time_read ( &time ); ASSEMBLY INTERFACE: MOVE.L #TIME_READ,D0 MOVE.L #TIME,A0 TRAP #1 PARAMETERS: D0 = command long word; A0 = pointer to where you want the value of the system "time" parameter placed. REGISTERS CHANGED: none. CAVEATS: none. RETURN VALUES: A0 points to the value of the system time parameter. Copyright (C) 1986, 1987 by Creative Software Technology 2-19 Advance Operating System Chapter 2 NAME: tick DESCRIPTION: Update the real-time clock by one unit (a single tick) of time. After the system time parameter is incremented by one unit of time, system call tick also looks to see if any tasks are in the delay list. If a task is found to be in the delay list, then tick will decrement the time parameter associated with that task. If a task times out (its time parameter decrements to $00000000) then ADVANCE will attempt to turn on the inactive task(s) that was(were) presently in the delay list. Tick will process all tasks in the delay list in the same manner. Many tasks could "spring back to life" with just a single call to tick (so long as each of the tasks time-out at the same time). Tick processes the delay list for tasks currently in delay. System call tick has only to scan the first delay node to deter- mine if there are any tasks currently in the delay list. Tick does not scan some fixed-length delay list. If there are two tasks somewhere in the delay list then system call tick will have spent time scanning and processing only those two delay nodes. There is therefore very little overhead in the tick software. TYPICAL USAGE: tick (); ENTRY CONDITIONS: User Mode or System Mode. ASSEMBLY INTERFACE: MOVE.L #TICK,D0 TRAP #1 PARAMETERS: D0 = command long word. REGISTERS CHANGED: none CAVEATS: If tick finds a task that has timed out, then ADVANCE will turn on the inactive task and place him at the end of the dispatch queue. RETURN VALUES: none Copyright (C) 1986, 1987 by Creative Software Technology 2-20 Advance Operating System Chapter 2 NAME: delay DESCRIPTION: Delay by some number of ticks, a tick being the basic unit of time. This call will automatically inactivate (turn off) the calling task. The calling task's stack is preserved intact. TYPICAL USAGE: delay ( ticks, &status ); ENTRY CONDITIONS: User Mode Only. ASSEMBLY INTERFACE: LINK A6,#-PARAMETER_TABLE LEA.L -STATUS(A6),A1 MOVE.L #500,D1 AMOUNT OF TICKS TO DELAY; MOVE.L #TIME,D0 COMMAND WORD PLACED IN D0; TRAP #1 PARAMETERS: D0 = command long word; D1 = number of ticks to delay; A1 = STATUS long word. ENTRY CONDITIONS: User Mode only. REGISTERS CHANGED: none. CAVEATS: The task making the call to delay will be de-activated until his timer has timed-out. When a sufficient number of TICKs have occurred, then the task is re-activated by placing it at the bottom of the current active process queue. This means that the system call "tick" must be used to eventually re-activate the tasks that have made a call to "delay." RETURN VALUES: If delay is invoked from the system mode, which is an ille- gal condition, and register A1 does not contain a $00000000, then the long word that A1 is pointing to will contain a -1. Copyright (C) 1986, 1987 by Creative Software Technology 2-21 Advance Operating System Chapter 2 NAME: put_char DESCRIPTION: Put a character to the default I/O device. ENTRY CONDITIONS: User Mode only. TYPICAL USAGE: put_char ( character ); ASSEMBLY INTERFACE: MOVE.L #CHAR,D1 MOVE.L #PUT_CHAR,D0 TRAP #1 PARAMETERS: D0 = command long word. D1 = byte of data to send to the default output device. The byte of data to be output is right justified (in the low byte of the low word) within D1. REGISTERS CHANGED: none. CAVEATS: If the system designer does not set up the "SERVPTR" parame- ter out_character properly (see chapter one) then ADVANCE will not output characters to the default output device. If SERVPTR is set to some non-zero value, and the second long word in the SERVPTR table (the table that SERVPTR points to) is non-zero, it should be a pointer to out_character (or some other routine with an RTS at the end of it) or the processor may end up in an illegal instruction exception. If you do not want to use this command and you do not want to use in_command, then set parameter SERVPTR equal to 0. RETURN VALUES: none Copyright (C) 1986, 1987 by Creative Software Technology 2-22 Advance Operating System Chapter 2 NAME: get_char DESCRIPTION: Get a character from the default I/O device. ENTRY CONDITIONS: User Mode only. TYPICAL USAGE: character = get_char(); ASSEMBLY INTERFACE: LEA.L CHARACTER(PC),A0 MOVE.L #GET_CHAR,D0 TRAP #1 PARAMETERS: D0 = command long word; A0 = the address where you want the character to be placed. REGISTERS CHANGED: None. CAVEATS: If the system designer does not set up the "SERVPTR" parame- ter in_character properly (see chapter one) then ADVANCE will not input characters from the default input device. If SERVPTR is set to some non-zero value, and the first long word in the SERVPTR table (the table that SERVPTR points to) is non-zero, it should be a pointer to in_character (or some other routine with an RTS at the end of it) or the processor may end up in an illegal instruction exception. If you do not want to use this command and you do not want to use out_command, then set parame- ter SERVPTR equal to 0. RETURN VALUES: A0 points to the address of the newly entered character. Copyright (C) 1986, 1987 by Creative Software Technology 2-23 Advance Operating System Chapter 2 NAME: key_stat1 DESCRIPTION: See if there is a character ready at the default I/O device. The user-supplied device driver must set the carry bit in the condition code register if a character is ready, and clear the carry bit if a character is not ready. User-supplied device driver must preserve registers A6 and A7. ENTRY CONDITIONS: User Mode only. TYPICAL USAGE: key_stat1 ( &err_stat, &dev_stat ); ASSEMBLY INTERFACE: LINK A5,#-PARM_TABLE NO_CHR LEA.L -ERR_STAT(A5),A1 TEL AOS/68K WHERE TO PUT LEA.L -DEV_STAT(A5),A0 ER STAT AND DEVICE STAT. MOVE.L #KEY_STAT1,D0 (KEY_STAT1 EQU $0000001A) TRAP #1 FORMAL AOS/68K CALL. MOVE.L (A1),D1 IF A1 POINTS TO TO A NON- BNE.S $ ZERO VALUE, NO EXIT. MOVE.L (A0),D1 NOW GET DEVICE STATUS. BEQ.S NO_CHR JUMP IF NO CHAR IS READY. PARAMETERS: D0 = command long word; A0 = the address where you want the status ( of the default i/o port) to be placed. REGISTERS CHANGED: None. CAVEATS: If the system designer does not set up the "SERVPTR" parame- ter key_stat1 properly (see chapter one) then ADVANCE will not attempt to call the key_stat1 routine. If SERVPTR is set to some non-zero value, and the third long word in the SERVPTR table (the table that SERVPTR points to) is non-zero, it should be a pointer to key_stat (or some other routine with an RTS at the end of it). RETURN VALUES: The long word that A1 points to will be equal to either a: Zero = no problems. Non-zero = no key_stat1 vector was found by AOS/68K The long word that A0 points to will be equal to either a: Zero = no character ready at the i/o device. Non-zero = a character is ready at the i/o device. Copyright (C) 1986, 1987 by Creative Software Technology 2-24 Advance Operating System Chapter 2 ADDITIONAL KEY_STAT EXAMPLES: Here is an assembly language example on how to get a character from the user i/o device - and - let the other tasks, task-share the processor: * Initialize as necessary: * LINK A5,#-PARM_TABLE * NO_CHAR LEA.L -ERR_STAT(A5),A1 <- Main task-share loop. LEA.L -DEV_STAT(A5),A0 Notice that you do not MOVE.L #KEY_STAT1,D0 need a TRAP #0 anywhere. TRAP #1 TRAP #1 will task-share. * * Optional: If you want to you may check to see what register * A1 is pointing to. If A1 points to a long word that has a non * zero value, then exit with some error because AOS/68K is * saying that it cannot find the key_stat1 vector in the config * table. If A1 points to a long word that has a zero value, then * continue your processing. * MOVE.L (A1),D1 SEE WHAT A1 IS POINTING TO. BNE.S ERROR * * If the device status long word that A0 points to is equal to a * $00000000, then there are no characters ready at the input * device. If the device status long word that A0 points to is * equal to a non-zero quantity, then you have a character ready * at the default i/o device. * MOVE.L (A0),D1 BEQ.S NO_CHAR IF D1 = 0, THEN NO CHARACTER. * * Now you know that a character is ready, make call to get_char: * LEA.L -ERR_STAT(A5),A1 LEA.L -CHAR(A5),A0 MOVE.L #GET_CHAR,D1 TRAP #1 MOVE.L (A1),D7 BNE.S ERROR IF D7 = 0, THEN NO ERROR * * You have no errors, great! Now fetch the character: * MOVE.L (A0),DX DX = CHARACTER. UNLK A6 RTS ERROR EQU $ Copyright (C) 1986, 1987 by Creative Software Technology 2-25 Advance Operating System Chapter 2 NAME: trn_stat1 DESCRIPTION: See if the transmit buffer in the default i/o device is ready to transmit a character. The user-supplied device driver must set the carry bit in the condition code register if the transmit register is ready to transmit, and clear the carry bit if the transmit register is not ready to transmit a character. User-supplied device driver must preserve registers A6 and A7. ENTRY CONDITIONS: User Mode only. TYPICAL USAGE: trn_stat1 ( &err_stat, &dev_stat ); ASSEMBLY INTERFACE: LINK A5,#-PARM_TABLE NO_TRN LEA.L -ERR_STAT(A5),A1 TEL AOS/68K WHERE TO PUT LEA.L -DEV_STAT(A5),A0 ER STAT AND DEVICE STAT. MOVE.L #TRN_STAT1,D0 (TRN_STAT1 EQU $0000001B) TRAP #1 FORMAL AOS/68K CALL. MOVE.L (A1),D1 IF A1 POINTS TO TO A NON- BNE.S $ ZERO VALUE, NO EXIT. MOVE.L (A0),D1 NOW GET DEVICE STATUS. BEQ.S NO_TRN JMP IF TRANS BUF NOT RDY. PARAMETERS: D0 = command long word; A0 = the address where you want the status ( of the default i/o port) to be placed. REGISTERS CHANGED: None. CAVEATS: If the system designer does not set up the "SERVPTR" parame- ter "trn_stat1" properly just behind the key_stat vector, then ADVANCE will not attempt to call the trn_stat1 routine. If SERVPTR is set to some non-zero value, and the fourth long word in the SERVPTR table (the table that SERVPTR points to) is non- zero, it should be a pointer to trn_stat1. RETURN VALUES: The long word that A1 points to will be equal to either a: Zero = no problems. Non-zero = no key_stat1 vector was found by AOS/68K The long word that A0 points to will be equal to either a: Zero = transmit register is not ready Non-zero = transmit register is ready to transmit a char. Copyright (C) 1986, 1987 by Creative Software Technology 2-26 Advance Operating System Chapter 2 NAME: gt_cpt DESCRIPTION: Get a pointer to the configuration table. Address register A0 contains a pointer to a memory location that contains a copy of the configuration table pointer. ASSEMBLY INTERFACE: MOVE.L #GT_CPT,D0 TRAP #1 MOVE.L (A0),D1 D1 NOW EQUALS ADDRESS OF CONFIG TBL PARAMETERS: D0 = command long word; A0 = the address where you want the address of the configuration table. REGISTERS CHANGED: None. CAVEATS: No special error trapping available. NAME: g_stk DESCRIPTION: Get a pointer to the value of the system stack pointer. ASSEMBLY INTERFACE: MOVE.L #G_STK,D0 TRAP #1 MOVE.L (A0),D3 D3 = VALUE OF SYSTEM STACK POINTER PARAMETERS: D0 = command long word; A0 = the address where you want the value of the system stack pointer. REGISTERS CHANGED: None. CAVEATS: No special error trapping available. Copyright (C) 1986, 1987 by Creative Software Technology 2-27 Advance Operating System Chapter 2 NAME: res_tsk DESCRIPTION: This command resets a task back to some initial condition. The calling program must know what the "reset" registers were. There are two ways to do this. The first way is to not have the task turned on initially by AOS/68K. You can then get the system stack pointer and the other two registers by looking at the REG dump. The other way is to write a macro that would first save the PC, and then the other registers of the "reset" location. A diagnostic program can then get them, turn off the target task, and send the saved registers to the res_tsk routine. ENTRY CONDITIONS: User Mode only. TYPICAL USAGE: res_tsk ( &status, ¶meters ); ASSEMBLY INTERFACE: LINK A5,#-PARMS A0 -> Task ID of target task LEA.L -REGS(A5),A0 New PC LEA.L -STAT(A5),A1 User stack pointer MOVE.L #RES_TSK,D0 System stack pointer TRAP #1 PARAMETERS: D0 = command long word. A0 = pointer to list of 4 long words that contain in the following order: 1) task id of the task to reset, 2) new PC, 3) user stack ptr, and 4) system stack ptr. If the task ID that A0 points to is at location $1000, then the new PC long word would be located at $1004, user stack pointer would be located at $1008, and the system stack pointer at $100C. REGISTERS CHANGED: none. CAVEATS: If the task you want to reset is not inactive, it will not get reset. Also, there is no error trapping. If you forget to load whatever A0 is pointing to with valid data, then your compu- ter system may boldly go where no computer has gone before. RETURN VALUES: The long word that A1 points to will have one of these codes (right justified within the long word) upon return from res_tsk: 00 = task was reset O.K. 01 - 04 = "tsk_on" error codes (these should never happen). 05 = task id you send is not an inactive task. Copyright (C) 1986, 1987 by Creative Software Technology 2-28 3.0 ADVANCE OPERATING SYSTEM CALLS (Part Two) The calls in chapter two are to be added to the existing commands in chapter 1. Some of the following calls may already be released. They are in this separate chapter because at the time of the release of this version of the manual the Chapter three calls were not out of beta test site. All AOS system calls require a minimum of 500 hours of run time in a variety of test conditions. AOS calls are randomly executed in regression test conditions to check for many types of run time problems. Here are some of the new AOS calls ready or nearly ready for release: NAME: fetch_mem DESCRIPTION: System call fetch_mem fetches 2K blocks of ram per call. A pointer is returned to the caller pointing to the newly allocated memory area. TYPICAL USAGE: memory_pointer = fetch_mem (); ENTRY CONDITIONS: User Mode or System Mode ASSEMBLY INTERFACE: LINK A6,#PARAMETER_TABLE LEA.L -STATUS(A6),A1 LEA.L -POINTER(A6),A0 MOVE.L #FETCH,D0 TRAP #1 PARAMETERS: D0 = command long word; A1 = address of STATUS; and A0 is where you want to put the pointer to ram. REGISTERS CHANGED: none. CAVEATS: none. RETURN VALUES: Parameter STATUS is reset to 0 if a call to fetch is successful and A0 points to the newly allocated 2K memory area. Otherwise, STATUS is set to the following error condition: $01 : There is not enough ram in the ram pool. Copyright (C) 1986, 1987 by Creative Software Technology 3-1 Advance Operating System Calls (Part Two) Chapter 3 NAME: release_mem DESCRIPTION: System call release_mem releases 2K blocks of memory back into the ram pool. ENTRY CONDITIONS: User Mode or System Mode TYPICAL USAGE: release_mem (pointer_to_2k_memory); ASSEMBLY INTERFACE: LINK A6,#PARAMETER_TABLE LEA.L -STATUS(A6),A1 MOVE.L #RELEASE,D0 TRAP #1 PARAMETERS: none REGISTERS CHANGED: none. CAVEATS: The area that you are returning to ADVANCE should not contain important parameters of any kind, as it will very likely be reassigned to the next task that makes a request for ram. RETURN VALUES: none. Copyright (C) 1986, 1987 by Creative Software Technology 3-2 Advance Operating System Calls (Part Two) Chapter 3 NAME: free_mem DESCRIPTION: This system call returns the number of 2K blocks of memory available in the ram pool. ENTRY CONDITIONS: User Mode or System Mode TYPICAL USAGE: siz_mem = free_mem (); ASSEMBLY INTERFACE: LINK A6,#PARAMETER_TABLE LEA.L -STATUS(A6),A1 LEA.L -SIZE(A6),A0 MOVE.L #FRE_MEM,D0 TRAP #1 PARAMETERS: D0 = command long word; A1 = address of STATUS; and A0 is a pointer to where you want to ADVANCE to put the number of 2K blocks of memory available. REGISTERS CHANGED: none. CAVEATS: none. RETURN VALUES: A0 points to a location that contains the number of 2K blocks of memory that are still available in the RAM POOL. Copyright (C) 1986, 1987 by Creative Software Technology 3-3 Advance Operating System Calls (Part Two) Chapter 3 NAME: edc_system DESCRIPTION: This call sets the system state table for edc processing. Ones and zeros in the 32-bit state table are used by the control module to process error detection and correction. Modules each make an edc_state() system call as to update to machine state whenever a significant change of state has occurred in their processing sphere of influence. TYPICAL USAGE: edc_system ( state ); ASSEMBLY INTERFACE: LINK A6,#PARAMETER_TABLE LEA.L -STATUS(A6),A1 MOVE.L #EDCS,D0 MOVE.L #EDC_STATE,D1 TRAP #1 PARAMETERS: none. REGISTERS CHANGED: none. CAVEATS: none. RETURN VALUES: none. Copyright (C) 1986, 1987 by Creative Software Technology 3-4 Advance Operating System Calls (Part Two) Chapter 3 NAME: edc_task DESCRIPTION: This is how a task communicates the low-level bit state of each task. As the task state changes dynamically, this informa- tion is sent to the control module, via an ADVANCE system algo- rithm. The control module (included with the EDC package) keeps an active record of the state of each task. This information is compared against the system state to see how many times a slave task can attempt to correct his local errors. This information is also used to see if a downstream process can continue, dispite the local error condition. TYPICAL USAGE: edc_task ( task_state, &stat ); ASSEMBLY INTERFACE: LINK A6,#PARAMETER_TABLE LEA.L -STATUS(A6),A1 MOVE.L #EDC_TSK,D0 MOVE.L #STATE,D1 TRAP #1 PARAMETERS: none. REGISTERS CHANGED: none. CAVEATS: none. RETURN VALUES: none. Copyright (C) 1986, 1987 by Creative Software Technology 3-5 4.0 CHAPTER FOUR - ERROR RECOVERY INTERFACE SOFTWARE The Error Recovery Interface software is included in Part 2 of the ADVANCE OPERATING SYSTEM, and is sold separately. Addi- tional information is available by requesting the complete ERI manual from your local ADVANCE salesman or by writing to Creative Software Technology Inc. A general overview is provided here so that engineers can glimpse into the theory behind the fault tolerant aspect of the ADVANCE OPERATING SYSTEM. Note: Please wait for the complete ERI Fault Tolerant User Manual before you set up data structures for error recovery algorithms. Real-time, multitasking operating systems with the software to detect and correct errors are more efficient than similar systems without error recovery mechanisms. Concurrent processing features work together with error recovery to to smooth out erratic process variables. These two features, combined with the AOS Balanced System design, mean much less down-time and more of the benefits associated with economical machine operation (such as scheduling small errors into a more timely preventative main- tenance schedule). Combinations of asynchronous errors that can not be planned for are methodically corrected (usually trans- parent to the machine operator) one at a time - fault tolerance. The optional Error Recovery (ERI) Interface to the ADVANCE Operating System is very powerful. Figure 4-1 illustrates how this feature works. The control module (included with the ERI software) receives a command from some external source to start the entire "ABC" process. The control module then tells modules A, AB, and ABC to return to the places where they were last processing when the "STOP" command was issued. In this illustration a non-fatal error (one that is correc- table) occurs in process AB1. There is processed product at ABC1, which is beyond the influence of the problem in process AB1. By use of a special, user-defined truth table, the control module determines that product at ABC1 can continue to ABC2 while the problem at AB1 is being corrected. Product at C1 can continue to C2, and so on. Thus the error does not hinder the throughput of the machine. But what happened to the error? The module in which the error occurred tells the control module the maximum reasonable number of attempts that should be made to try to correct the problem. An ERI subroutine is then executed which attempts correct the error. The control module keeps a count of the number of tries made to correct the error, while the unaffected part of the machine continues its normal processing. Copyright (C) 1986, 1987 by Creative Software Technology 4-1 Advance Operating System Chapter 4 The ERI subrou- tine finally cor- - - - - - - - - MODULE "ABC"- - - rects the problem at : _________ _____________ : AB1 before reaching : | | | | : the maximum number : | ABC2 |___| PROCESS ABC | : of tries. The con- : | | | COMPLETE | : trol module then : |_________| |_____________| : releases the module : ^ - - - - - - - - - that was in trouble : ____|______ : to continue on from : | | : PROCESS wherever it was when : | SYNC PROC |<---- C2 <---- C1 the error occurred. : | ABC1 | : ERI has allowed con- : |___________| : tinuous processing - - - ^ - - - - of product and has - - - | - - - - MODULE "AB" - - - - - prevented an expen- : ____|___ ________ ________ : sive and time-wast- : | | | | | | : ing shutdown. If : | AB4 |<--| AB3 |<--| AB2 | : the ERI subroutine : |________| |________| |________| : fails to correct a - - - - - - - - - - - ^ : working module's : ______|____ : problem after the PROCESS : | | : maximum allowable B1 -----> B2 ------>| SYNC PROC | : number of tries, the : | AB1 | : control module shuts : |___________| : down the entire ABC - - - -^- - - process and notifies - - - - - - - - MODULE "A"- - -|- - - the operator of the : ___________ | : type of problem. : | | ____|____ : The operator or a : | START | | | : maintenance techni- : | PROCESS |----------->| A2 | : cian must then cor- : | A1 | |_________| : rect the error. : |___________| : Once he corrects the : : error, processing - - - - - - - - - - - - - - - - - - - continues. Figure 4-1 ERI Illustration 4.1 Error Analysis Most controllers have two basic types of errors. These two types of are either correctable errors or fatal errors. A correctable error is defined to be an error that can be corrected in a finite amount of time without stopping the work in progress. A fatal error is defined to be a rare situation where there is no certain hope of quick error recovery. The latter type of error causes an immediate shutdown of the local processing associated with the error condition. Copyright (C) 1986, 1987 by Creative Software Technology 4-2 Advance Operating System Chapter 4 After analyzing various types of supposed fatal error condi- tions in many types of process controllers, it can be found with some assurance that most "fatal" errors are really not fatal errors. Most present day "fatal" errors are the by-product of unbalanced multitasking systems. In an unbalanced multitasking system, tasks are given an unequal amount of functionality. Unbalanced systems are usually not able to achieve true fault tolerance. Since the Balanced System design was discussed in detail in Chapter One, it will not be discussed in great detail here. In addition to problems associated with an unbalanced system, programmers in many design teams do not know from a system wide standpoint how a particular error condition can be corrected at some point in their program. Fault tolerance must be designed in from the beginning, not as an afterthought. The following graph shows the relative efficiency elements of most process control systems with increasing levels of error detection and correction. The graph is not drawn to any particular scale, nor does it represent test cases from any real- time process. It is reproduced to show the relative positions of the different levels of fault tolerance. Notice the big improvement in throughput for just the Level 1 ERI. Higher levels of efficiency are obtainable. There is a big jump in efficiency from no ERI to Level one ERI. One obtains a lesser and lesser efficiency return for each higher level in ERI. The curve represents equal improvements in fault tolerance for each level of ERI. The ordinate axis represents the number of units of processed parts, times 1000 for example. The abscissa represents equal units of time. | - - - - - - - - X Level 4 ERI | | 20 | - - - - - - - - - -X Level 3 ERI | | | 15 | - - - - - - - - - - - - X Level 2 ERI | | | | 10 | - - - - - - - - - - - - - - - - -X Level 1 ERI | | | | | 5 | - - - - - - - - - - - - - - - - - - - - - - - - - X | | | | | No ERI 0 +-------1--------2+--+----3--------4--------5-------+6 Figure 4-2 4.2 Error Correction Word Each working module has a data table containing pointers to that module's correction subroutines. The control module uses these data tables when correcting errors. A very efficient error code substructure links all ERI processing together. When a task had an error, the task sends a message to the control module. The message is a pointer to the error correction word. The error word tells the Control Module everything necessary in order to try to clear the entering task's error record. Copyright (C) 1986, 1987 by Creative Software Technology 4-3 Advance Operating System Chapter 4 Here is a "C" language template for the various terms in the ERI word, to see the scope of the data elements: struct ERI_WORD_MODE_0 { unsigned fatal_bit_m0 : 1, /* 1 = not correctable */ error_source_m0 : 3, /* source of the error */ error_mode_m0 : 1, /* error mode */ error_level_m0 : 3, /* task error state */ error_index_m0 : 4, /* main error index */ forever_bit_m0 : 1, /* 1 = correct forever */ numb_of_tries_m0 : 7, /* # tries to correct */ reserved_m0 : 8; /* reserved byte */ }; struct ERI_WORD_MODE_0 { unsigned fatal_bit_m1 : 1, /* 1 = not correctable */ error_source_m1 : 3, /* source of the error */ error_mode_m1 : 1, /* error mode */ error_level_m1 : 3, /* task error state */ error_index_m1 : 4, /* main error index */ alt_error_index_m1 : 4, /* alternate error idx */ number_of_tries_m1 : 4, /* # tries to correct */ alternate_tries_m1 : 4, /* alternate # tries */ reserved_m1 : 8; /* reserved byte */ }; 4.2.1 General Description 4.2.1.1 Correctable or Non-correctable The most significant bit of information (bit31) tells the Control Module if the error is correctable or fatal. If the bit is set to TRUE then the errant module never returns from the Error_to_Control subroutine. No error recovery techniques are started. This situration eventually causes the upstream processing, or system operator, to do some form of system reset. 4.2.1.2 Error Source Field The next three bits (bits 30, 29, and 28) tells the Control Module the source of the error. These three bits allow for reporting seven major sources of errors. 4.2.1.3 Error Mode In cases where this bit is set to TRUE, some of the error bytes are sub-divided to do a certain type of conditional case statement. If TRUE, the Error Correction Word is sub-divided to handle cases where the following situation happens: Try to fix Copyright (C) 1986, 1987 by Creative Software Technology 4-4 Advance Operating System Chapter 4 this situation by doing some algorithm X number of times. If this does not correct the situation then do some other algorithm Y number of times. If that does not work then do whatever you normally do as described in the Error State (described next). 4.2.1.4 Error State The next three bits are very interesting. Tasks are given the ability to tell the ERI task just how many times to try to correct the error. If after the maximum number of attempts to correct the error, and the error is not corrected, the Control Module looks at the Error State bits (bits 26, 25, and 24) to see what the final state of the error is to become. An error that was thought to be correctable may now become "fatal." 4.2.1.4.1 Error State Four The "100" Error State is a request (after the maximum error tries) for a system soft stop. The calling task wants to get the attention of the operator by sending a warning message of some type. This error state also permits the logging of critical warning information if required. If expedient to do so the Control Module will stop the process at a convenient time and send the message, etc. If the operator or controlling process sends a restart command of some type, the process is restarted and the Control Module error base for the calling task is cleared. The calling task is returned to the place in his code just past the call to the error_to_control call. The whole "100" error process is usually called a "casual message" request. Use error state four when the sensor or whatever needs cleaning, there is too much noise in the logic supply line, it's coffee time, etc. 4.2.1.4.2 Error State Three The "011" Error State forces the system (after max tries) to soft stop. The calling task has something so important to get accross to the operator that it cannot possibly wait any longer. Not only will the system soft stop, but a warning message will be sent and the warning condition will be logged if necessary. This condition is still non-fatal, however. Once the machine operator presses the "RUN" switch the Control Module clears the error base for the calling module. And again, the calling module is returned to the place in its code just past the call to the error_to_control call. Use this error state whenever something potentially dangerous might happen if the warning message is not heeded, etc. Copyright (C) 1986, 1987 by Creative Software Technology 4-5 Advance Operating System Chapter 4 4.2.2.1.4.3 Error State Two The "010" Error State is a serious error condition. If after maximum number of error correction attempts the ERI has not corrected the error, Error State Two now instructs the Control Module that the calling task has caused a serious system fault. The calling task is not returned to its code. The process comes to an immediate soft stop, logs the error and sends the errant task's message to the operator and/or upstream controller. A system re-start is required to reset the errant task. The unusual feature of Error State Two is that the other modules are not directly affected. Only the errant module is shut down. Many times in real-world error conditions a process can carry on without some important function for a short time. If the rest of the tasks cannot carry on without the missing task, then the process will not run. If they can run, then fine. The other tasks run as soon as the operator presses the start switch again. The operator (test engineer, upstream controller, etc) starts the process again on local authority. This situation is not always a fatal error condition. To give a more clear example of the use of Error State Two take into condition the following situation. Suppose that you have a task that computes the checksum of all eprom data. Also suppose that it runs at an average priority level as all tasks do the the AOS Balanced System design. If for any reason you swap out a table, change a byte of data, or in any way change the effective checksum of current eprom data, you will immediately cause the checksum task to halt the whole system (if the checksum task is allowed to run). The checksum task is therefore given an error recovery routine that sets the Error State Two condition to TRUE if ERI fails to correct the problem in a short amount of time. The system could run without the checksum task. 4.2.1.4.4 Error State One Error State One "001" is one of the most serious error states. If after the maximum number of attempts to correct the error and the ERI does not correct the incomming task's error, then the system does a hard stop. Some major error has now occurred (not a loss of power, however) and the calling task is not released from the error_to_control routine. None of the other system tasks are supposed to be able to function, theor- etically. A system re-start (or reset) is necessary to make everyting work again. Use this error state cautiously. Copyright (C) 1986, 1987 by Creative Software Technology 4-6 Advance Operating System Chapter 4 4.2.2 Error Correction Index Code This byte (bits 23, 22, 21, 20, 19, 18, 17, and 16) is used as an index into an error correction table. Each task has a data control block that directs the ERI routine into the proper correction algorithm. This structure is a table of pointers to self-contained, error correction algorithms for that particular task. In mode 1, however, the error correction index code is broken down into two, four bit indices. Error mode 1, however, is more powerful as it instructs the Control Module to try to correct the error one way first, and if the problem is not corrected then try to fix the error the other way. 4.2.3 Number of Tries This is the calling tasks key to how many times the ERI routine will attempt to correct the reported error condition. In mode 0, for instance, you can have up to 127 attempts to correct an error condition. If this byte is negative (bit 15 = 1) then this instructs the ERI routine, and thusly the Control Module, to try to fix the error as many times as is expedient to do so from a system point of view. The calling task is not required to know all the various states that the other tasks are in to make this decision. On the Control Module knows the overall state of the system. In mode 1 this field represents two four bit quantities (with no negative bit, or fix forever algorithm). The Number of Tries byte represents bits 16, 17, 18, 19, 20, 21, 22, and 23 in the Error Correction Word. Copyright (C) 1986, 1987 by Creative Software Technology 4-7 5.0 CHAPTER FIVE - INTERACTIVE DIAGNOSTIC MODULE (IDM) The Interactive Diagnostic Module is sold as a 8K byte EPROM (or available on a MS-DOS formatted disk as a Motorola S19 record). The IDM is position independent and can operate almost anywhere in the 68K memory map, except over the exception table vectors, etc. The standard AOS configuration table governs the way the user registers the IDM with AOS. The Task Number for the IDM has to be the ASCII characters "ID" ($4944). The amount of stack needed for the IDM is 2K bytes. The "PCTR" vector is the beginning address of wherever you decide to locate the IDM in your 68K memory map. The optional IDM created for the ADVANCE Operating System is also called the debug module. This module runs concurrently with the application layer, for two major reasons. First, the programmer can get an "inside view" of the software as it runs. Second, the module can overcome the basic deficiencies of most logic analyzers. Logic analyzers cannot trap just one module or "task" in a multitasking system without halting the whole system. The ADVANCE background diagnostics can selectively trap just one task. The other tasks continue to run unaffected. Logic analy- zers also usually have to halt the system in order for the pro- grammer to modify code. The ADVANCE debug module can modify code without halting the system. Also, the debug module can trap intermittent errors without the machine being taken apart for examination and without the use of logic cables. The background diagnostics include an easy-to-use hexa- decimal editor. This utility permits interactive examination and modification of application layer code or parameter data. The hex editor can also "block-move" data and independently execute program subroutines. Whenever application code is in RAM, pro- grammers can easily locate and change conditional branch errors. In addition, the debug module allows breakpoints, a powerful tool in multitasking situations. A programmer can interactively capture or stop the first module to hit a break point. He can examine and modify the module's registers as necessary. He can even change its program counter so that the module returns to a location different from the one it came from. Breakpoints do not directly affect the other modules. They "capture" only the module that hits one of them. The other modules continue to run. Hitting a breakpoint, of course, temporarily prevents the captured module from executing any code beyond the breakpoint. There are many other useful features included in the ADVANCE Operating System diagnostics. Of the remaining features, how- ever, the "link" is the most powerful (The Link software may or may not be ready at the time this manual is released - if you need this command, then check with CST before you order the IDM Copyright (C) 1986, 1987 by Creative Software Technology, 5-1 Advance Operating System Chapter 5 to make sure this command is ready). This diagnostic lets the programmer link the terminal connected to the target system through to the development station (See Fig. 5-1). The target system then becomes transparent. The programmer may work with the target system or the development station from the same terminal. This link is available whether or not the application layer is running. Because the linking feature operates in the back- ground, the application layer runs real-time and unaffected. The link software (which is contained in the debug module) uses only a small slice of processor time. _____ ___________________________________________________ | | | | | BUS |--|I/O PORT SLAVE CPU 3 | | | |___________________________________________________| | | | | | BUS |--|I/O PORT SLAVE CPU 2 | | | |___________________________________________________| | | ________ ___________ | | _______| |________________| |_____ | HOST| | | MOTORS | SLAVE | SOLENOIDS | | | CPU | | |________| CPU 1 |___________| | | | | | | | | | | |_____ AOS/68K ________| | | | | | | ________|__ | | | TASK 1------------TASK 2 | | | | | | | -| SENSORS | | BUS |--|I/O PORT---CONTROL TASK 3----| |___________| | | | | | | | | |_____| | ------- IDM ------ -|CONTROLLERS| | ________ | | ______ |___________| | | | | | | | | | |I/O PORT|------ -------|RS-232| | |________|________|________________|______|_________| | | _________|___________ ____|_____ | I/O PORT | | RS-232 | | | | | | | | | | DEVELOPMENT STATION | | TERMINAL | |_____________________| |__________| Figure 5-1 Typical IDM Application Copyright (C) 1986, 1987 by Creative Software Technology, 5-2 Advance Operating System Chapter 5 5.1 IDM Command Parser The IDM uses a simple command parser to extract information from the command line. There are several special characters that can be used to control user input: CTRL-H backspace one character. CTRL-X go to beginning of command string. CTRL-Z redisplay cmd line till CR character found. CTRL-C redisplay cmd line till CR character found. CR enter the command line into the parser. If a valid command line is present from a former command, and the user wants to run the same command again, just entering a CR will execute the last command line. This feature is very useful, for example, when you want to view a section of memory over and over again by just hitting the <CR> key. There are up to four command line arguments, in addition to the command itself. You do not have to enter leading zeros with any command line argument. Numbers are read in hexadecimal for the most part, as the IDM operates in the hexadecimal mode. 5.2 IDM Vectors There are just two vectors associated with the IDM itself. The most important vector is the starting location of the IDM. The IDM starts at the top of it's location in 68000 memory (it's lowest memory address). If IDM will occupy memory locations $4000 to $5FFF, for instance, the IDM's starting address will be at $4000. The breakpoint vector is located exactly 4 bytes from the starting vector. The IDM presently uses Trap #0, Trap #1, and Trap #2. To use the IDM, you must first point Trap #0 to the correct AOS/68K dispatch routine that you are using. Next, point Trap #1 to AOS/68K "Entry ONE". Finally, point Trap #2 to the IDM breakpoint vector at location IDM+4. If your system has trap 0 - 2 already in use, we will make simple trap changes in the IDM at no additional charge. Just let your dealer or CST know in advance what IDM trap modifications are necessary, and we will be happy to make them for you. Copyright (C) 1986, 1987 by Creative Software Technology, 5-3 Advance Operating System Chapter 5 5.3.1 Edit Memory EDIT The Edit Memory command is used to display memory a byte at a time. You may also modify data or enter new data. In addi- tion, you may also enter text into memory or execute subroutines. OPTION DESCRIPTION S Skip one byte forward through memory R Return backwards one byte in memory / Look at the same memory location again X Execute subroutine at present address <0..F> Enter Hexadecimal data into memory Gxxxx <CR> Go to location xxxx in memory T Enter text mode; CTRL-C to exit mode <CR> Enter <CR> to exit Edit Memory EXAMPLES: IDM 1.0 >EDIT 000000F0 00 + G4801 00004801 FF + S 00004802 FF + R 00004801 FF + R 00004800 DF + / 00004800 DF + 12 00004801 FF + 34 00004802 56 V + R 00004801 34 4 + R 00004800 12 + S 00004801 34 4 + G4804 00004804 FF + T Structured^C 0000480F 41 A + G4804 00004804 53 S + S 00004805 74 t + S 00004806 72 r + S 00004807 75 u + S 00004808 63 c + S 00004809 74 t + S 0000480A 75 u + S 0000480B 72 r + S 0000480C 65 e + S 0000480D 64 d + S 0000480E 03 + G4810 00004810 4E N + S 00004811 75 u + R 00004810 4E N + X 00004810 4E N + IDM 1.0 > Copyright (C) 1986, 1987 by Creative Software Technology, 5-4 Advance Operating System Chapter 5 5.3.2 Memory Dump MDMP xxx yyy The MDMP command is used to display a section of memory beginning at address xxx and ending with the address yyy. If xxx is greater than yyy then yyy equals the number of bytes of memory to dump. The IDM runs in the background and the memory you want to display may be changing even as you display it. If you want a "snapshot" of a section of memory, block move the section you want to look at into a buffer with the BMOV command. Once the memory is in a static buffer you can view the memory with MDMP. EXAMPLES: IDM 1.0 >MDMP 4800 481F 004800 12 34 56 78 53 74 72 75 63 74 75 72 65 64 20 41 .4VxStructured A 004810 6E 61 6C 79 73 69 73 03 77 FF FF FF FF FF FF FF nalysis.w....... * 1020 * IDM 1.0 >MD 5700 20 005700 44 65 73 69 67 6E 20 69 73 20 74 68 65 20 74 68 Design is the th 005710 69 6E 6B 69 6E 67 20 70 72 6F 63 65 73 73 20 74 inking process t * 0BE6 * 5.3.3 Checksum Memory CHEK xxx yyy The CHEK command is used to checksum a section of memory beginning at address xxx and ending with the address yyy. If xxx is greater than yyy then yyy equals the number of bytes of memory to checksum. EXAMPLES: IDM 1.0 >CHEK 5700 20 * 0BE6 * IDM 1.0 >CHEK 4800 481F * 1020 * Copyright (C) 1986, 1987 by Creative Software Technology, 5-5 Advance Operating System Chapter 5 5.3.4 Register Display REG xxx yyy zzz The REG command is used to display the MC68000 processor registers of the specified task. The xxx parameter is the task id, yyy , if present, is the register you want to change with parameter zzz. If yyy and xxx are not present in the command line, then task xxx's MC68000 processor registers are dumped. The internal IDM REG software takes a "snapshot" of the register save area on the target task's stack. The snapshot of the registers is then formated and sent to the user default output device. The registers that will be seen at any output baud rate are the stacked registers at the instant in time when the user enters a <CR> in the command line just after the REG .. command. All data and address registers can be changed except the system stack pointer and the user stack pointer (A7). The Status Register can be modified by the REG command by entering "SR" as the yyy parameter. IDM 1.0 >REG 5431 D4 12345 IDM 1.0 >REG 5431 PC=0000211C SR=0000 SYSTK=00007000 D0=000001D0 D1=00000000 D2=00000000 D3=00000000 D4=00012345 D5=00000075 D6=00000000 D7=000001D7 A0=000001A0 A1=00003B16 A2=00000000 A3=00000000 A4=00000000 A5=00003B1A A6=000001A6 A7=00003B02 IDM 1.0 >REG 5431 PC ABCDEF IDM 1.0 >REG 5431 PC=00ABCDEF SR=0000 SYSTK=00007000 D0=000001D0 D1=00000000 D2=00000000 D3=00000000 D4=00012345 D5=00000075 D6=00000000 D7=000001D7 A0=000001A0 A1=00003B16 A2=00000000 A3=00000000 A4=00000000 A5=00003B1A A6=000001A6 A7=00003B02 IDM 1.0 > Copyright (C) 1986, 1987 by Creative Software Technology, 5-6 Advance Operating System Chapter 5 5.3.4 No Breakpoint NBRK xxxx The NBRK instruction information was presented here before the breakpoint information so that references to NBRK could be made. Please see the section on breakpoints for a complete discussion on the use of breakpoints. There are certain restric- tions on the use of breakpoints. The NBRK command is used to remove a breakpoint from the internal breakpoint table, and functions as the inverse of the BPNT command (the BPNT command puts breakpoints into user pro- grams). If a task had formerly encountered a certain breakpoint, then if the NBRK command is executed with the xxxx parameter equal to the original breakpoint parameter, that task will return back to its original instruction. The task would continue from where the breakpoint was to wherever the remaining code takes the task. When the user removes the breakpoint that caused the task to become inactive, the IDM puts the original instruction back into the code and activates the task made inactive by a breakpoint. Parameter xxxx is the former breakpoint address. If NBRK is entered with no argument, then ALL of the breakpoints are removed at the same time. Many tasks could possibly spring back to life with a single NBRK <CR> command. This assumes each task had already encountered a breakpoint. Sometimes the NBRK command returns "NO BREAKPOINTS". This occurs just after you have removed a breakpoint and there are no breakpoints left in the breakpoint table. In the following example there was a breakpoint already in the breakpoint table. The original breakpoint was at $211C. EXAMPLE: IDM 1.0 >NBRK 211C NO BREAKPOINTS IDM 1.0 > Copyright (C) 1986, 1987 by Creative Software Technology, 5-7 Advance Operating System Chapter 5 5.3.5 Breakpoint BPNT xxx Parameter xxx is the even word address of where you want the breakpoint to be placed. If xxx is not an even word then an error message is displayed. Once the breakpoint parameter is placed in memory and the opcode saved, etc., the IDM displays all of the breakpoint addresses in the breakpoint table. If BPNT is entered with no arguments, then a list of outstanding breakpoints is output to the user default output device. When a task (or module) encounters a breakpoint, that task is made inactive by the IDM breakpoint software. When the user removes the breakpoint that caused the task to become inactive, the IDM puts the original instruction back into the code and activates the task. The BPNT command sets one address into the breakpoint address table. The breakpoint table can hold up to eight breakpoint addresses. After the breakpoint has been entered into the breakpoint table, the original opcode is saved and the breakpoint is inserted into the actual code. If the IDM software notices that the code is not modified (such as trying to put a breakpoint in ROM) then an error message is returned: BREAKPOINT DID NOT STORE. Breakpoints will only work in a RAM debugging environment. A TRAP #2 instruction is inserted into the user program as soon as a <CR> is entered in the command line. Since the IDM operates in the background, a breakpoint may occur immediately. When a task hits a breakpoint, the task id for the module is immediately displayed and then the symbol "@BP" just to the right of the task id. In the following example their was a task with an id of "T1" that immediately hit the breakpoint as soon as the user hit the <CR> key. The run time breakpoint software dis- played the "5431 @BP" and the IDM displayed the "00211C". EXAMPLE: IDM 1.0 >BPNT 211C 5431 @BP 00211C IDM 1.0 >REG 5431 PC=0000211C SR=0000 SYSTK=00007000 D0=000001D0 D1=00000000 D2=00000000 D3=00000000 D4=00000000 D5=00000075 D6=00000000 D7=000001D7 A0=000001A0 A1=00003B16 A2=00000000 A3=00000000 A4=00000000 A5=00003B1A A6=000001A6 A7=00003B02 IDM 1.0 >NBRK 211C NO BREAKPOINTS Copyright (C) 1986, 1987 by Creative Software Technology, 5-8 Advance Operating System Chapter 5 IDM 1.0 >REG 5431 PC=00002118 SR=0000 SYSTK=00007000 D0=000001D0 D1=00000000 D2=00000000 D3=00000000 D4=00000000 D5=000000A7 D6=00000000 D7=000001D7 A0=000001A0 A1=00003B16 A2=00000000 A3=00000000 A4=00000000 A5=00003B1A A6=000001A6 A7=00003B02 IDM 1.0 >BPNT NO BREAKPOINTS IDM 1.0 >BPNT 211A 5431 @BP 00211A IDM 1.0 >BPNT 2156 00211A 5432 @BP 002156 IDM 1.0 >BPNT 00211A 002156 IDM 1.0 >NBRK 211A 002156 IDM 1.0 >BPNT 002156 IDM 1.0 >NBRK 2155 INVALID BREAKPOINT ADDRESS IDM 1.0 >NBRK 2154 BREAKPOINT NOT IN TABLE IDM 1.0 >NBRK 2156 NO BREAKPOINTS IDM 1.0 > - PLEASE NOTE - Tasks that will be debugged using breakpoints have to regis- ter a mailbox with AOS. This is easily done with the AOS post_box command. The breakpoint software is the only IDM fea- ture that requires use of an already working task mailbox. The task mailbox itself is very easy to set up by using the examples in the AOS User Manual manual. If the same task will be receiv- ing letters from all the other tasks, then make parameter MAX_LTRS equal to the number of registered tasks, plus one, and there should never be a problem with breakpoints. Copyright (C) 1986, 1987 by Creative Software Technology, 5-9 Advance Operating System Chapter 5 Breakpoints must be used in the user mode only. For proper breakpoint operation, place breakpoints in sections of code that a known, registered task, operating in the user mode, will be encountering. Please do not place breakpoints in interrupt rou- tines. For debugging interrupt routines you will have to use some other debugging technique, such as desk-checking, a logic analyser, tracing, etc. We are constantly improving the ADVANCE Operating System Tools. We may already have interrupt debugging tools not men- tioned in this edition of the IDM manual. The present breakpoint restrictions are, in practice, very minimal. The IDM breakpoint software works very well in a majority of debugging situations. We will be sending additional IDM debugging information to all of our registered customers as soon as enhancements are available. * * * Copyright (C) 1986, 1987 by Creative Software Technology, 5-10 Advance Operating System Chapter 5 5.3.6 Fill Block of Memory MFIL xxx yyy zzz The Fill Block of Memory command fills memory with parameter zzz. Parameter zzz is a word size. Parameter xxx is the begin- ning address of where to start filling memory and parameter yyy is the ending address of where to stop filling memory with word size parameter zzz. Both xxx and yyy must be even addresses. If, however, yyy is less than xxx, then yyy is considered to be the number of words you want to fill starting at location xxx. If yyy is less than xxx, then yyy does not have to be an even word, of course. It is just a counter value. EXAMPLES: IDM 1.0 >MDMP 5900 30 005900 DF FF FF FF FF FF 19 F6 FF FF FF FF FF FF FF FF ................ 005910 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ................ 005920 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ................ * 2EC1 * IDM 1.0 >FMEM 5910 8 ABCD IDM 1.0 >MDMP 5900 592F 005900 DF FF FF FF FF FF 19 F6 FF FF FF FF FF FF FF FF ................ 005910 AB CD AB CD AB CD AB CD AB CD AB CD AB CD AB CD ................ 005920 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ................ * 2A91 * IDM 1.0 >FMEM 5910 591F 0123 EVEN ADRS REQ FOR WORD FILL IDM 1.0 >FMEM 5910 591E 3210 IDM 1.0 >MDMP 5900 30 005900 DF FF FF FF FF FF 19 F6 FF FF FF FF FF FF FF FF ................ 005910 32 10 32 10 32 10 32 10 32 10 32 10 32 10 32 10 2.2.2.2.2.2.2.2. 005920 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ................ * 20E1 * Copyright (C) 1986, 1987 by Creative Software Technology, 5-11 Advance Operating System Chapter 5 5.3.7 Block Move a Block of Memory BMOV xxx yyy zzz Block Move moves a block of memory starting from address xxx to address yyy to a second block of memory area starting at address zzz. If parameter yyy is less than xxx then yyy is the number of BYTES to block move. You may use even or odd address for the beginning and ending address parameters in the BMOV command. Memory can be moved over itself in either an upward or downward direction. EXAMPLES: IDM 1.0 >MDMP 56F0 572F 0056F0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 005700 44 65 73 69 67 6E 20 69 73 20 74 68 65 20 74 68 Design is the th 005710 69 6E 6B 69 6E 67 20 70 72 6F 63 65 73 73 20 74 inking process t 005720 68 61 74 20 68 61 73 20 74 6F 20 70 72 65 63 65 hat has to prece * 11B1 * IDM 1.0 >BMOV 5700 20 56FA IDM 1.0 >MDMP 56F0 572F 0056F0 00 00 00 00 00 00 00 00 00 00 44 65 73 69 67 6E ..........Design 005700 20 69 73 20 74 68 65 20 74 68 69 6E 6B 69 6E 67 is the thinking 005710 20 70 72 6F 63 65 73 73 20 74 63 65 73 73 20 74 process tcess t 005720 68 61 74 20 68 61 73 20 74 6F 20 70 72 65 63 65 hat has to prece * 13F3 * IDM 1.0 >MDMP 57F0 582F 0057F0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 005800 44 65 73 69 67 6E 20 69 73 20 74 68 65 20 74 68 Design is the th 005810 69 6E 6B 69 6E 67 20 70 72 6F 63 65 73 73 20 74 inking process t 005820 68 61 74 20 68 61 73 20 74 6F 20 70 72 65 63 65 hat has to prece * 11B1 * IDM 1.0 >BMOV 5800 581F 5807 IDM 1.0 >MD 57F0 582F 0057F0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 005800 44 65 73 69 67 6E 20 44 65 73 69 67 6E 20 69 73 Design Design is 005810 20 74 68 65 20 74 68 69 6E 6B 69 6E 67 20 70 72 the thinking pr 005820 6F 63 65 73 73 20 74 20 74 6F 20 70 72 65 63 65 ocess t to prece * 1192 * IDM 1.0 > Copyright (C) 1986, 1987 by Creative Software Technology, 5-12 Advance Operating System Chapter 5 5.3.8 Help with Commands HELP The HELP command presently displays the commands that are available to the user. In order to save some code space, just the commands are displayed, not how to use them. Once you are familiar with the IDM commands, you may use just the first two letters of each command. IDM 1.0 >HELP EDIT MDMP CHEK BPNT NBRK HELP ECHO REG FMEM BMOV STOR SRCH LOAD STAT ON OFF LINK IDM 1.0 > 5.3.9 Store Parameter STOR xxxx y zzzz Store parameter is used to store a word or long word parame- ter in memory. Since the IDM is frequently running in the back- ground, you may have to modify some addresses and data with one store to memory. Another program may be actively looking at some parameter (IDM Edit Memory command EDIT, can change a byte at a time and is not be designed to change an address with just one store to memory). Parameter xxxx is the parameter you wish to store to memory at even address location zzzz. Parameter "y" is either a "W" or a "L", which stands for Word stores or Long word stores. EXAMPLES: IDM 1.0 >STOR ABCD L 5708 IDM 1.0 >MDMP 56F0 571F 0056F0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 005700 00 00 AB CD 67 6E 20 69 73 20 74 68 65 20 74 68 ....gn is the th 005710 69 6E 6B 69 6E 67 20 70 72 6F 63 65 73 73 20 74 inking process t * 1692 * Copyright (C) 1986, 1987 by Creative Software Technology, 5-13 Advance Operating System Chapter 5 5.1.0 Block of Memory Search SRCH wwww xxxx yyyy zzzz The block of Memory Search function, SRCH, searches for either a byte, word, or long word in a block of memory. Parameter wwww is the starting address, parameter xxxx is the ending address, and yyyy is the argument to search for. Parameter zzzz is either a "B", "W", or "L". EXAMPLES: IDM 1.0 >SRCH 1000 2000 234 W 001703 0234 IDM 1.0 > 5.1.1 System Status STAT xxxx IDM command STAT returns the status of the specified task. If parameter xxxx is present, STAT returns just the status of that task, whether it is active or inactive (or non-registered). If parameter xxxx is not present in the command line then STAT returns the status of every registered task. If you enter STAT with no task id's, the resulting dump of tasks STATUS information may not be representative of the real system under examination. IDM command STAT gets the status of each task just before it outputs each line of STATUS information. The task ID's and their names are correct, of course, but in between the time IDM went to get the task status and the time it was displayed, the task may have been turned on or off. EXAMPLES: IDM 1.0 >STAT 5431 TASK ID TASK NAME STATUS 5431 "Mod One " ACTIVE IDM 1.0 >STAT TASK ID TASK NAME STATUS 5431 "Mod One " ACTIVE 5432 "Mod Two " INACTIVE IDM 1.0 > Copyright (C) 1986, 1987 by Creative Software Technology, 5-14 Advance Operating System Chapter 5 5.1.2 Echo to Output Device ECHO The IDM command ECHO toggles the ECHO flag. The ECHO flag is usually set to true and can be shut off by entering ECHO <CR>. When you send characters to the IDM through the input device and the ECHO flag is ON, then all characters sent to the IDM will be echoed back to the input device. 5.1.3 Turn On a Task ON xxxx The IDM command "ON" turns on any inactive task. Parameter xxxx is the task id of the task you want to turn on. 5.1.4 Turn Off a Task OFF xxxx The IDM command "OFF" turns off any active task. Parameter xxxx is the task id of the task you want to turn off. 5.1.5 Load a File LOAD xxxx AOS command LOAD loads files in the Motorola S19 record format. Parameter xxxx is a 2's compliment offset, which is added to the load offset of each incomming S1 record. 5.1.6 Link Default Devices LINK The IDM command LINK connects together the default I/O device number one with default I/O device number two. If a development station is connected to device number two, then you can make changes to your source file, through the IDM, all the time while your former object code is running. When changes are made to the source and you have compiled and linked your changes, you may download the new object file through default I/O device number two. Two exit the LINK mode, enter a CTRL-Y. You may write a small routine for the development station to delay for about 20 - 30 seconds while you exit the LINK mode and use the IDM LOAD command. Many development systems support some sort of BATCH processing command language (JCL, VCL, etc) which makes programmed delays and such very easy to impliment. You may also write a macro command to do the prompting from both ends. The IDM supports both envorinments. Copyright (C) 1986, 1987 by Creative Software Technology, 5-15 Advance Operating System Chapter 5 5.4.0 Information for Advanced Programmers 5.4.1 Breakpoints When a breakpoint is encountered, the breakpoint software saves the contents of the task's mailbox. The breakpoint software makes the task that encounters a breakpoint send a letter with the address of the breakpoint to the IDM. The breakpoint software then forces the task to make a call to the AOS command "receive," and turns off the calling task until the IDM sends a letter to the inactive task. When instructed by the user, via IDM's NBRK command, the IDM sends a letter to the inactive task. The original task environment is restored, the original opcode is put back into the code and the task is then reactivated. Copyright (C) 1986, 1987 by Creative Software Technology, 5-16 *** Advance Operating System Setup Examples *** TITLE SAMPLE.ASM * * EXAM.ASM * * Example Assembly Language Setup Code * * DATE: 01.09.86 * REVISED: 02.25.86 * * This section of assembler code is included so programmers * can see exactly how to set up mailboxes, tasks, and so forth. * The following code originally comes from a regression test * program that was used to test the IDM. The entire listing is not * reproduced, just the setup code. This code ran on a MEX68KECB/D2 * (Motorola 68000 trainer) board. * EXTERN REGD EXTERN FILL EXTERN BLKM EXTERN ST EXTERN LOAD EXTERN ON EXTERN OFF * GLOBAL RDCHAR GLOBAL PRCHAR GLOBAL RDHEX GLOBAL PRHEX GLOBAL TALK GLOBAL CRLFED * *============== EQUATES: * _BYTE EQU 1 _WORD EQU _BYTE*2 _LONG EQU _WORD*2 * * AOS Commands: * SEND EQU $09 SENDX EQU $0B NEW SEND CMD; RDCX EQU $98 Bit 7 set! No task switch. PRCX EQU $99 Bit 7 set! No task switch. KY_STA1 EQU $1A Added extra command 02.10.87 TR_STA1 EQU $1B Added extra command 02.16.87 POSTBX EQU $48 RECEIVE EQU $14A GT_CPT EQU $20 %0010 0000 - Not necessary to set bit 7; * EMPTY EQU 0 LETTE EQU 2 TASK MAILBOXES HOLD ONLY 2 LETTERS; LETTERS EQU 8 OUR MAILBOX HOLDS 8 LETTERS; ETX EQU 3 CTRLC EQU $03 RESTART THE INPUT COMMAND LINE (^C); Creative Software Technology Assembler Setup Examples Page 1 *** Advance Operating System Setup Examples *** BEL EQU $07 BEEP (WARNING MESSAGE); BS EQU $08 BACK SPACE; TAB EQU $09 TAB; CR EQU $0D CARRIAGE RETURN; LF EQU $0A CTRLX EQU $18 RESTART THE INPUT COMMAND LINE (^X); CTRLZ EQU $1A REPRINT THE PREVIOUS INPUT COMMAND LINE (^Z); SPC EQU $20 SPACE; OUTPUT EQU 243 TRPA 14 FUNCTION # - OUTPUT STRINTG TO PORT 1; INCHE EQU 247 TRAP 14 FUNCTION # - INPUT SINGLE CHARACTER; OUTCH EQU 248 TRAP 14 FUNCTION # - OUTPUT SINGLE CHARACTER; * *============== BREAKPOINT EQUATES: * MSIZE EQU 8 SIZE, OR WIDTH OF LETTERS IN MAIL BOX; NUMBPS EQU 8 EIGHT BREAKPOINTS ARE ALLOWED; * SP_MSK EQU $D0 TSKID EQU $04 NBR_BP EQU $08 THERE ARE 8 BREAKPOINTS IN THE TABLE BREAK EQU $4E42 EQU "BREAK" ($4E42) IS A TRAP #2 COMMAND; SS_SIZE EQU 256 SYSTEM STACK SIZE; * INACTV EQU 0 ACTIVE EQU 1 * TASK1 EQU 1 TASK2 EQU 2 * TRAP0V EQU $80 TRAP1V EQU $84 TRAP2V EQU $88 * DATA * *============== STACK FRAME: * LOCALS EQU 0 * * Breakpoint table is an array 8 bytes wide by 8 long: * * # of | 2 | breakpoint | * hits <--bytes--> <------ address ------> * ------------------------------------------------- * 1 | : | : | : | : | : | : | : | : | * |--:--|--:--|--:--|--:--|--:--|--:--|--:--|--:--| * 2 | : | : | : | : | : | : | : | : | * |--:--|--:--|--:--|--:--|--:--|--:--|--:--|--:--| * : * |--:--|--:--|--:--|--:--|--:--|--:--|--:--|--:--| * 8 | : | : | : | : | : | : | : | : | * ------------------------------------------------- * | val | | actual | 4 | * op code <-op code-> <------- bytes -------> Creative Software Technology Assembler Setup Examples Page 2 *** Advance Operating System Setup Examples *** * ORG LOCALS DUMMY STACK TEMPLATE; RMB _BYTE VOC EQU $-LOCALS Valid Op Code; RMB _BYTE NOH EQU $-LOCALS Number Of Hits; RMB _WORD OPC EQU $-LOCALS OP Code; RMB _LONG BPA EQU $-LOCALS BreakPoint Address; BPT_WD EQU BPA BreakPointTable WiDth; * ORG LOCALS MEASUR EQU $ RECVR RMB _LONG SENDR RMB _LONG ATRIB RMB _LONG MLBOX RMB _LONG POBSZ EQU $-MEASUR * ORG LOCALS BREAKPOINT HANDLER MAILBOX TEMPLATE; MF RMB 2 MAIL FLAG; ML RMB 2 MAX LETTERS; LT EQU $-MF * ORG LOCALS VALID RMB _LONG RAMPTR RMB _LONG RAMSIZE RMB _LONG AUXRST RMB _LONG AUXDSP RMB _LONG SERVPTR RMB _LONG DATAPTR RMB _LONG NTASKS RMB _LONG * * Now set up stack frames for dummy tasks. Each task must have mail box. * ORG LOCALS A5L RMB _LONG MFRAM EQU $ RMB _LONG STATZ EQU $-MFRAM RMB 2 Reserve space for mailbox flag; MLFLAG EQU $-MFRAM RMB 2 Reserve space for number of letters; MXLTRS EQU $-MFRAM RMB _LONG*4 LEAVE ROOM FOR 2 LETTERS; PSIZ EQU $-MFRAM * * Now make room for breakpoint software mail box and other parameters: * Creative Software Technology Assembler Setup Examples Page 3 *** Advance Operating System Setup Examples *** RMB 2 Reserve space for mailbox flag; ML_FLAG EQU $-FRAME RMB 2 Reserve space for number of letters; MX_LTRS EQU $-FRAME RMB MSIZE*NUMBPS 8 LETTERS, ONE EACH FOR EACH BREAKPOINT; BPT EQU $-FRAME RMB 64 Reserve space for NUMBPS breakpoints (8?). RMB 70 RSA EQU $-FRAME * PSIZE EQU $-FRAME * *%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% * % * START OF EXAMPLE APPLICATION PROGRAM % * % *%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% * CODE * ORG $2000 * _VALID BYTE 'VLID' _RAMPTR LONG $3800 _RAMSIZ LONG $1000 _AUXRST LONG $0000 _AUXDSP LONG $0000 _SRVPTR LONG SERVEC _DPTR LONG SSTACK _NTASKS LONG $0003 * LONG DUMY1 BYTE 'Mod One ' LONG $200 LONG $0000 LONG $0000 WORD ACTIVE .BYTE 'T1' * LONG DUMY2 BYTE 'Mod Two ' LONG $200 LONG $0000 LONG $0000 WORD INACTV SOMETHING DIFFERENT FOR A CHANGE; .BYTE 'T2' * LONG IDM BYTE 'Mod Thre' LONG $280 LONG $0000 LONG $0000 WORD ACTIVE .BYTE 'ID' UNIQUE TASK_ID FOR IDM MODULE; Creative Software Technology Assembler Setup Examples Page 4 *** Advance Operating System Setup Examples *** * *============== SERVEC: * * The service vector locations will be 16 vectors (eventually). The * first 8 are reserved for in_character, out_character, etc. The last * eight are user defined service routines. * SERVEC LONG GET LONG PUT LONG KST LONG TST * SSTACK LONG SS_SIZE * *============== GET: * * Get's charter in life is to input characters from the user default * i/o device. Get is also a hook into ADVANCE, telling ADVANCE where * and how to get characters from the user-supplied input device. * * Entry conditions: * * A0 = place where we put the input character * GET MOVEM.L D1-D7/A0-A6,-(A7) MOVE.B #INCHE,D7 TRAP #14 AND.L #$00FF,D0 REMOVE MOTO'S UPPER WORD GARBAGE; MOVEM.L (A7)+,D1-D7/A0-A6 MOVE.L D0,(A0) RTS * *============== PUT: * * Put's charter in life is to output characters from the user default * i/o device. Put is also a hook into ADVANCE, telling ADVANCE where * and how to get characters from the user-supplied output device. * * Entry conditions: * * D1 = character you want to output to the user-supplied device. * PUT MOVEM.L D0-D7/A0-A6,-(A7) MOVE.L D1,D0 MOTO WANTS CHAR IN D0; AND.L #$00FF,D0 MOVE.L #OUTCH,D7 TRAP #14 MOVEM.L (A7)+,D0-D7/A0-A6 RTS * *============== KST: * KST ORI #$01,CCR Fake key status routine. RTS Creative Software Technology Assembler Setup Examples Page 5 *** Advance Operating System Setup Examples *** * *============== TST: * TST ORI #$01,CCR Fake trans_stat routine. RTS * *============== REGRESSION TESTER STARTS HERE: * START LEA.L INIT(PC),A0 MOVE.L A0,TRAP0V TRAP #0 GET INTO SUP MODE AND CONTINUE: * * You must enter the ADVANCE OPERATING SYSTEM from the user mode. We * are now in the 68000 supervisor mode (the supervisor bit is set = 1). * INIT MOVE.W (A7)+,D0 DISCARD SR MOVE.L (A7)+,D0 DISCARD PC MOVE.L #$1400,A0 MOVE.L A0,TRAP1V INIT AOS SYSTEM CALL VECTOR; MOVE.L #$1800,A0 MOVE.L A0,TRAP0V INIT DISPATCH VECTOR; LEA.L BPHT(PC),A0 MOVE.L A0,TRAP2V INIT BREAKPOINT VECTOR; JUMP $1000 JUMP TO AOS/68K; * *============== Dummy task number 1: * * VERY IMPORTANT: All tasks wanting to use breakpoints must Post Mailbox. * DUMY1 LINK A5,#-PSIZ RESERVE SPACE ON STACK FOR INPUT COMMAND LINE; LEA.L -MLFLAG(A5),A0 LEA.L -STATZ(A5),A1 MOVE.W #EMPTY,-MLFLAG(A5) MOVE.W #LETTE,-MXLTRS(A5) SETUP FOR "LETTE" LETTERS (WAS 2); MOVE.L #POSTBX,D0 TRAP #1 POST MAILBOX; * MOVEA.L #$01A0,A0 MAKE IT EASY TO SEE REGISTERS ON STK; MOVEA.L #$01A6,A6 MOVE.L #$01D0,D0 MOVE.L #$01D7,D7 DMY15 TRAP #0 NOP ADDQ.L #1,D5 BRA.S DMY15 * *============== Dummy task number 2: * * VERY IMPORTANT: Post Mailbox. * DUMY2 LINK A5,#-PSIZ RESERVE SPACE ON STACK FOR INPUT COMMAND LINE; LEA.L -MLFLAG(A5),A0 LEA.L -STATZ(A5),A1 MOVE.W #EMPTY,-MLFLAG(A5) Creative Software Technology Assembler Setup Examples Page 6 *** Advance Operating System Setup Examples *** MOVE.W #LETTE,-MXLTRS(A5) SETUP FOR "LETTE" LETTERS (WAS 2); MOVE.L #POSTBX,D0 TRAP #1 POST MAILBOX; * MOVEA.L #$02A0,A0 MOVEA.L #$02A6,A6 MOVE.L #$02D0,D0 MOVE.L #$02D7,D7 DMY25 TRAP #0 NOP ADDQ.L #1,D6 BRA.S DMY25 * *%%%%%%%%%%%%%% END OF EXAMPLE APPLICATION PROGRAM %%%%%%%%%%%%%% * * *================================================================ * = * Beginning of Interactive Diagnostic Module = * = *================================================================ * IDM BRA IDM2 JUMP TO MAIN IDM CODE; * * In order to use the AOS breakpoint feature, System Architects simply * point TRAP #2 to this next, known location: * BPHT BRA BPH NEVER CHANGE THIS VECTOR * REVISED .BYTE '0102MEASAAAABCIG' .BYTE 'AAABCREA230SAZ99' * CPYWRTE .BYTE ' ADVANCE OPERATING SYSTEM ' .BYTE '(C) COPYRIGHT 1987 BY ' .BYTE 'CREATIVE SOFTWARE TECHNOLOGY ' .BYTE 'P.O.BOX 1856 ' .BYTE 'CHANDLER, ARIZONA 85226-1856 ' .BYTE 'ALL RIGHTS RESERVED ' * IDM2 LINK A6,#-PSIZE RESERVE SPACE ON STACK FOR INPUT COMMAND LINE; MOVEA.L A6,A5 BSR INITZ BSR CLRALL CLEAR ALL BREAKPOINTS; * * VERY IMPORTANT: Post Mailbox. * LEA.L -ML_FLAG(A5),A0 LEA.L -STAT(A5),A1 MOVE.W #EMPTY,-ML_FLAG(A5) MOVE.W #LETTERS,-MX_LTRS(A5) MOVE.L #POSTBX,D0 TRAP #1 * Creative Software Technology Assembler Setup Examples Page 7 Advance Operating System Appendix A ADVANCE OPERATING SYSTEM EXECUTION TIMES The timing information in this Appendix in given to assist engineers and programmers in the development of application pro- grams for the ADVANCE OPERATING SYSTEM. The timing information given in this appendix is based upon an average 68000 system with eight registered tasks. The 68000 is running under the following conditions: 1) Processor clock frequency is 8MHz. 2) No wait states are incurred in ROM or RAM accesses. 3) No user extension code is present. 4) Calls are made from assembly language. 5) Dynamic RAM refresh time is not included. Four of the eight registered tasks are in the active dispatch queue and four are inactive. The cases selected for each call are not the best for performance. System designers can achieve better times than the execution times in this appendix. It is also possible under certain conditions, however, to exceed the times listed below for various conditions. The selected cases may or may not be representative of what a particular application will encounter. Note: System designers do not have to add in task switching time to any of the following execution times. Included in all of the execution times is the time it takes to switch to the next task. All timing figures are given in microseconds. task_switch: Execute a simple task switch. No user hooks are present. This is the execution time of the Entry TWO task switch routine................................73.5 task_switch: Execute a task switch and supply hooking mechanism for executing user-supplied code. Do not include the time it takes to execute the user code itself. This is the execution time of the Entry THREE task switch routine....................................86.1 tsk_on: Turn on any registered task in the inactive dispatch queue...........................247 tsk_off: Turn off any registered task in the active dispatch queue.............................334 tsk_stat: Get the status of any registered task (on/off)......................................181 tsk_id: Get the task number of any calling task..................................................154 Copyright (C) 1986, 1987 by Creative Software Technology A-1 Advance Operating System Appendix A post_box: Post the mail box of any registered task...............................................207 send: Send a message to any registered active task (that has already posted it's mailbox with AOS)..........................................................296 send: Send a message to any regis- tered inactive task (that has al- ready posted it's mailbox with AOS) and turn on the inactive task.................................415 Both of the "receive" execution times include the "tsk_off" execu- tion time because system call "receive" calls tsk_off: receive: Make a call to receive and allow a message from any task to turn you back on again.....................................378 receive: Make a call to receive and let only one specific task turn you back on again.............................................439 time_set: Simply set the system time parameter................................................139 time_read: Simply read the system time parameter................................................140 tick: Update the real-time clock by a single unit of time and decre- ment delays if present. Do not turn on any tasks.............................................156 tick: Update the real-time clock by a single unit of time and decrement delays if present. Also, turn on a task that has timed out.............................295 delay: Make a call to delay. This time includes (task switching time and) a call to tsk_off........................................381 read_character: Read in a charac- ter from the user-supplied input device. Do not include any execu- tion time for user code.......................................162 Copyright (C) 1986, 1987 by Creative Software Technology A-2 Advance Operating System Appendix A put_character: Put a character to the user-supplied output device. Do not include any execution time for user code.................................................161 key_stat: See if a character is ready at the default user-supplied input device..................................................171 trn_stat: See if default i/o dev- ice is ready to transmit......................................171 get_config: Get a pointer to the configuration table...........................................131 get_sys_stack: Get the value of the system stack pointer......................................132 Note: The "Return Quick" version (rq_tsk_on, etc) of AOS/68K commands have approximately the same execution times as their non-return quick version. Copyright (C) 1986, 1987 by Creative Software Technology A-3 Advance Operating System Ordering Information AOS is distributed in the USEware format. If you are going to USE it, please check the appropriate box below and enclose a check or purchase order. If you find the program unUSEable, please drop us a line telling us why. If you pay for the program by sending in a signed Binary Software License Agreement with a check or money order for the correct amount, you will receive a copy of the Advance Operating System IDM (Interactive Diagnostic Module) object code, a $395.00 value, at no additional charge, be added to our mailing list, and be kept notified of new releases and new utilities. Please fill out the following Binary Software License Agreement and Order Form when registering your software: ----------------------------------------------------------------- BINARY SOFTWARE LICENSE AGREEMENT Customer Name:___________________________________________________ Address:_________________________________________________________ License Number___________________________________________________ Creative Software Technology, ("CST"), P.O. Box 1856, Chandler, Arizona, 85244-1856, and the party who executes this Agreement ("Customer") are in complete agreement as follows: 1. The Software Programs. The "Software Programs" consist of binary object code for CST's computer programs ordered under this Binary Software License Agreement, in CST's standard form and format at the time of which CST has the Software Programs delivered to the customer. "Software Documentation" consists of the user manuals and other related materials which are made available by CST with the Advance Operating System Software. All title, right, and interest in and to all non-embedded copies of the Advance Operating System Software and the Software Documenta- tion are and shall at all times remain the sole and exclusive property of CST. Customer acknowledges CST's representation that CST is the exclusive owner of all intellectual rights, copy- rights, all other rights and all versions of the Advance Opera- ting System Software and Software Documentation. 2. Grant of Licenses. CST hereby grants to Customer and Customer hereby accepts: 2.1 License to Use. A non-exclusive, and transferable license to use the Software Programs and the Software Documenta- tion; and 2.2 License to Make Permitted Number of Copies*. A non- exclusive, personal, and non-transferable license, subject to the all of the conditions of Paragraph 3, to copy the Advance Opera- ting System Software Programs and embed no more than the Permit- ted Number of Copies* into, and to distribute them with, other Customer computer software or hardware having substantial added Copyright (C) 1986, 1987 by Creative Software Technology A-4 Advance Operating System Ordering Information value. Customer may copy and distribute the Advance Operating System Software Documentation in it's original, unmodified, ARC formatted form. 2.3 Term of Licenses. Unless earlier terminated in writing to Creative Software Technology, the Licenses granted above shall continue perpetually from the date hereof. Upon termination or expiration of this Agreement, Customer shall notify CST of the reason for termination in writing. 3. Permitted Copying. Customer agrees that it will not disassemble the Advance Operating System Software Programs for the purpose of obtaining a source listing. Customer has no right to authorize any one else to modify or disassemble the Advance Operating System software. Customer may make the Permit- ted Number of Copies* if the Customer complies with each of the following conditions: 3.1 Ownership of Software. Customer agrees that each non- embedded copy of Software shall be the sole and exclusive proper- ty of CST, except as provided by Paragraph 6.2 below; 3.2 Proprietary Notices. Customer shall, immediately after copying, securely affix a CST EPROM Labels containing CST's copy- right and proprietary notices to each and every copy of the Software Programs. 3.3 Record-Keeping. Customer shall keep an account of the number of copies made of the Advance Operating System Software Programs and the location of all copies in its possession. 4. Warranties. CST warrants that the Advance Operating System Software Program will perform substantially as described in the Advance Operating System User Manual, except for the system calls described in Chapter 3 of the Advance Operating System User Manual. CST will, at no extra charge, fix any bugs discovered in the Advance Operating System Software Programs for one year after the shipment date and for each additional year during which an Annual Update Service is purchased by Customer. CST makes no other warranties, either express of implied, inclu- ding any implied warranties of merchantability of fitness for a particular purpose. Customer is advised to test the Advance Operating System software program thoroughly before relying on it. Customer must assume the entire risk of using the Advance Operating System Software Programs. Neither CST nor anyone else who has been involved in the creation or production of the Advance Operating System Software Programs or Software Documenta- tion, shall be liable for indirect, or consequential damages resulting from their use. Customer's sole remedy shall be cor- rection or replacement of the Advance Operating System Software Program. Copyright (C) 1986, 1987 by Creative Software Technology A-5 Advance Operating System Ordering Information 5. Payment. Customer shall fill out the appropriate ordering form below, and pay CST the correct amount stated on the ordering form for the Permitted Number of Copies* within 30 days of the ordering date. 6. Indemnity by CST. CST shall indemnify and hold Customer harmless from any claim that the Advance Operating System Soft- ware Programs or Software Documentation violate someone else's patent or copyright if Customer (a) gives CST prompt written notice of any and all claims, and (b) provides CST with the information, authority, and assistance CST deems reasonably necessary for its defense. In the event use of the Advance Operating System Software Programs are enjoined, CST shall, in its sole discretion and at its own expense, either (i) procure the right for continued use, (ii) provide the modifications necessary to make use non-infringing, or (iii) refund Customer for the amount paid under this Agreement for Permitted Number of Copies* whose use is enjoined. 7. General. This Agreement shall be governed by the laws of the State of Arizona and/or applicable federal law. If part of this Agreement is found to be invalid by a court of competent jurisdiction, the remaining provisions shall remain in full force and effect. Any modifications to this agreement must be in writing and signed by both parties. IN WITNESS WHEREOF, the parties have executed this Agreement as of the date written below. Signed: ____________________________ Date: ___________ (Customer) Title: ____________________________ Signed: ____________________________ Date: ___________ (CST) Title: ____________________________ Copyright (C) 1986, 1987 by Creative Software Technology A-6 Advance Operating System Ordering Information Single-Installation Order Form ============================== If you are going to pay for a single copy, use this form. The single installation price is $995.00. Arizona businesses please add 6.5% sales tax. Full Name:___________________________ 1 copy @ $995.00=_________ IDM source code =_________ Address :___________________________ 6.5% Sales Tax =_________ :___________________________ Total Enclosed =_________ City, St.:____________________ ________ Zip:_________________ ----------------------------------------------------------------- Corporate Site License Order Form ================================= If you are going to be using multiple copies of AOS within your company at one site, (5 mile radius from licensing party), you need only pay $995.00 for the first copy plus $10 per additional copy. We have 45 day billing if you include a P.O. number instead of a check or money order. Primary Corporate Contact for updates, etc.: Full Name :_________________________ 1 copy @ $995.00=_________ *Permitted Number of Copies @ $10.00=_________ IDM source code =_________ Address :_________________________ 6.5% Sales Tax =_________ :_________________________ Total Enclosed =_________ Department:_________________________ P.O. Number:______________ City, St. :_________________ _______ Zip:_________________ Authorized Signature:____________________________ Date:_________ Make checks payable to: Creative Software Technology P.O. Box 1856 Chandler, Az 85244-1856 Business Tel: (602) 961-0231 8:00 A.M. till 4:00 P.M.* M-F CST RBBS Tel: (602) 961-0231 4:00 P.M. till 6:30 P.M.* M-F * Phoenix, Arizona time. Modem line is 300/1200 baud, 8 data bits, 1 stop bit, no parity. Copyright (C) 1986, 1987 by Creative Software Technology A-7